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

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


Как да пишем? .[#toc-how-to-write]
----------------------------------

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

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

Също така научете [синтаксиса |syntax]. За предварителен преглед на статията по време на писане можете да използвате [редактора за предварителен преглед |https://editor.nette.org/].


Мутации на езика .[#toc-language-mutations]
-------------------------------------------

Английският е основният език, така че промените трябва да бъдат на английски. Ако английският не е силната ви страна, използвайте [DeepL Translator |https://www.deepl.com/translator] и други ще проверят текста ви.

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


Тривиални редакции .[#toc-trivial-edits]
----------------------------------------

За да допринесете за документацията, трябва да имате акаунт в [GitHub |https://github.com].

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

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

Тъй като [редакторът за предварителен преглед |https://editor.nette.org/] няма възможност за запазване на промените директно в GitHub, трябва да копирате изходния текст в клипборда (с помощта на бутона *Копирай в клипборда*) и след това да го поставите в редактора в GitHub.
Под полето за редактиране се намира форма за изпращане. Тук не забравяйте да обобщите накратко и да обясните причината за вашата редакция. След подаване се създава т.нар. заявка за теглене (PR), която може да се редактира допълнително.


По-големи редакции .[#toc-larger-edits]
---------------------------------------

По-подходящо е да се запознаете с основите на работата със системата за контрол на версиите Git, вместо да разчитате единствено на интерфейса на GitHub. Ако не сте запознати с Git, можете да се обърнете към [ръководство git - the simple |https://rogerdudler.github.io/git-guide/] и да помислите за използване на някой от многото налични [графични клиенти |https://git-scm.com/downloads/guis].

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

1) в GitHub създайте [разклонение на |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) след това направете промени в [съответния клон |#Documentation Structure]
4) проверете за допълнителни интервали в текста с помощта на инструмента [Code-Checker |code-checker:]
5) запишете (commit) промените
6) ако сте доволни от промените, изпратете ги в GitHub във вашето разклонение
7) оттам ги изпратете в хранилището `nette/docs`, като създадете [pull request|https://help.github.com/articles/creating-a-pull-request] (PR)

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


Структура на документацията .[#toc-documentation-structure]
-----------------------------------------------------------

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

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