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

Допринасянето към документацията е една от най-полезните дейности, тъй като помагате на другите да разберат 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.

Съдържанието на всеки branch се разделя на основни папки, представляващи отделните области на документацията. Например application/ отговаря на https://doc.nette.org/bg/application, latte/ отговаря на https://latte.nette.org и т.н. Всяка такава папка съдържа подпапки, представляващи езиковите версии (cs, en, bg, …) и евентуално подпапка files с изображения, които могат да бъдат вмъквани в страниците на документацията.