Как да допринесете към документацията ************************************* .[perex] Допринасянето към документацията е една от най-полезните дейности, тъй като помагате на другите да разберат framework-а. Как да пишем? ------------- Документацията е предназначена предимно за хора, които се запознават с темата. Затова трябва да отговаря на няколко важни точки: - Започнете от простото и общото. Към по-напредналите теми преминете едва накрая - Опитайте се да обясните нещата възможно най-добре. Опитайте например първо да обясните темата на колега - Посочвайте само тази информация, която потребителят действително трябва да знае по дадената тема - Проверете дали вашата информация е наистина вярна. Тествайте всеки код - Бъдете кратки - това, което напишете, съкратете наполовина. А след това спокойно още веднъж - Пестете всякакви видове подчертавания, от удебелен шрифт до рамки като `.[note]` - В кодовете спазвайте [Стандарта за кодиране |coding-standard] Освойте също [синтаксиса |syntax]. За преглед на статията по време на писането й можете да използвате [редактор с преглед |https://editor.nette.org/]. Езикови версии -------------- Основният език е английският, така че вашите промени трябва да бъдат на чешки и английски. Ако английският не е вашата силна страна, използвайте [DeepL Translator |https://www.deepl.com/translator] и другите ще проверят текста ви. Преводът на други езици ще бъде извършен автоматично след одобрение и финализиране на вашата корекция. Тривиални корекции ------------------ За да допринесете към документацията, е необходимо да имате акаунт в [GitHub|https://github.com]. Най-лесният начин да направите дребна промяна в документацията е да използвате връзките в края на всяка страница: - *Покажи в GitHub* отваря изходния вид на дадената страница в GitHub. След това е достатъчно да натиснете бутона `E` и можете да започнете да редактирате (необходимо е да сте влезли в GitHub) - *Отвори преглед* отваря редактор, където веднага виждате и крайния визуален вид Тъй като [редакторът с преглед |https://editor.nette.org/] няма възможност да запазва промените директно в GitHub, е необходимо след завършване на корекциите да копирате изходния текст в клипборда (с бутона *Copy to clipboard*) и след това да го поставите в редактора в GitHub. Под полето за редактиране има формуляр за изпращане. Тук не забравяйте да обобщите накратко и да обясните причината за вашата корекция. След изпращане се създава т.нар. pull request (PR), който може да бъде редактиран допълнително. По-големи корекции ------------------ По-подходящо, отколкото да използвате интерфейса на GitHub, е да сте запознати с основите на работа със системата за контрол на версиите Git. Ако не владеете работата с Git, можете да разгледате ръководството [git - the simple guide |https://rogerdudler.github.io/git-guide/] и евентуално да използвате някой от многото [графични клиенти |https://git-scm.com/downloads/guis]. Редактирайте документацията по този начин: 1) В GitHub си създайте [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] на хранилището [nette/docs |https://github.com/nette/docs] 2) [Клонирайте |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] това хранилище на своя компютър 3) След това в [съответния branch |#Структура на документацията] направете промените 4) Проверете за излишни интервали в текста с помощта на инструмента [Code-Checker |code-checker:] 4) Запазете промените (commit) 6) Ако сте доволни от промените, изпратете ги (push) в GitHub към вашия fork 7) Оттам ги изпратете към хранилището `nette/docs`, като създадете [pull request|https://help.github.com/articles/creating-a-pull-request] (PR) Обичайно е да получавате коментари със забележки. Следете предложените промени и ги обработете. Добавете предложените промени като нови commit-и и отново ги изпратете в GitHub. Никога не създавайте нов pull request заради корекция на съществуващ pull request. Структура на документацията --------------------------- Цялата документация е разположена в GitHub в хранилището [nette/docs |https://github.com/nette/docs]. Текущата версия е в `master`, по-старите версии са разположени в branch-ове като `doc-3.x`, `doc-2.x`. Съдържанието на всеки branch се разделя на основни папки, представляващи отделните области на документацията. Например `application/` отговаря на https://doc.nette.org/bg/application, `latte/` отговаря на https://latte.nette.org и т.н. Всяка такава папка съдържа подпапки, представляващи езиковите версии (`cs`, `en`, `bg`, ...) и евентуално подпапка `files` с изображения, които могат да бъдат вмъквани в страниците на документацията.

Как да допринесете към документацията

Допринасянето към документацията е една от най-полезните дейности, тъй като помагате на другите да разберат framework-а.

Как да пишем?

Документацията е предназначена предимно за хора, които се запознават с темата. Затова трябва да отговаря на няколко важни точки:

Започнете от простото и общото. Към по-напредналите теми преминете едва накрая
Опитайте се да обясните нещата възможно най-добре. Опитайте например първо да обясните темата на колега
Посочвайте само тази информация, която потребителят действително трябва да знае по дадената тема
Проверете дали вашата информация е наистина вярна. Тествайте всеки код
Бъдете кратки – това, което напишете, съкратете наполовина. А след това спокойно още веднъж
Пестете всякакви видове подчертавания, от удебелен шрифт до рамки като .[note]
В кодовете спазвайте Стандарта за кодиране

Освойте също синтаксиса. За преглед на статията по време на писането й можете да използвате редактор с преглед.

Езикови версии

Основният език е английският, така че вашите промени трябва да бъдат на чешки и английски. Ако английският не е вашата силна страна, използвайте DeepL Translator и другите ще проверят текста ви.

Преводът на други езици ще бъде извършен автоматично след одобрение и финализиране на вашата корекция.

Тривиални корекции

За да допринесете към документацията, е необходимо да имате акаунт в GitHub.

Най-лесният начин да направите дребна промяна в документацията е да използвате връзките в края на всяка страница:

Покажи в GitHub отваря изходния вид на дадената страница в GitHub. След това е достатъчно да натиснете бутона E и можете да започнете да редактирате (необходимо е да сте влезли в GitHub)
Отвори преглед отваря редактор, където веднага виждате и крайния визуален вид

Тъй като редакторът с преглед няма възможност да запазва промените директно в GitHub, е необходимо след завършване на корекциите да копирате изходния текст в клипборда (с бутона Copy to clipboard) и след това да го поставите в редактора в GitHub. Под полето за редактиране има формуляр за изпращане. Тук не забравяйте да обобщите накратко и да обясните причината за вашата корекция. След изпращане се създава т.нар. pull request (PR), който може да бъде редактиран допълнително.

По-големи корекции

По-подходящо, отколкото да използвате интерфейса на GitHub, е да сте запознати с основите на работа със системата за контрол на версиите Git. Ако не владеете работата с Git, можете да разгледате ръководството git – the simple guide и евентуално да използвате някой от многото графични клиенти.

Редактирайте документацията по този начин:

В GitHub си създайте fork на хранилището nette/docs
Клонирайте това хранилище на своя компютър
След това в съответния branch направете промените
Проверете за излишни интервали в текста с помощта на инструмента Code-Checker
Запазете промените (commit)
Ако сте доволни от промените, изпратете ги (push) в GitHub към вашия fork
Оттам ги изпратете към хранилището nette/docs, като създадете pull request (PR)

Обичайно е да получавате коментари със забележки. Следете предложените промени и ги обработете. Добавете предложените промени като нови commit-и и отново ги изпратете в GitHub. Никога не създавайте нов pull request заради корекция на съществуващ pull request.

Структура на документацията

Цялата документация е разположена в GitHub в хранилището nette/docs. Текущата версия е в master, по-старите версии са разположени в branch-ове като doc-3.x, doc-2.x.