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

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

Как да пишем?

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

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

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

Мутации на езика

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

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

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

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

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

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

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

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

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

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

в GitHub създайте разклонение на хранилището nette/docs
клонирайте това хранилище на вашия компютър
след това направете промени в съответния клон
проверете за допълнителни интервали в текста с помощта на инструмента Code-Checker
запишете (commit) промените
ако сте доволни от промените, изпратете ги в GitHub във вашето разклонение
оттам ги изпратете в хранилището nette/docs, като създадете pull request (PR)

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

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

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

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