--- url: https://next.zammad.org/sr/contribute/style-guide.md --- # Водич кроз стил и садржај Овај водич вам пружа преглед садржаја Zammad документације, као и упутства за форматирање и стилизовање текста ради јасноће и читљивости. Први одељци садрже уопштене информације и правила. [Одељак са примерима](#examples) је на крају. Уколико имате додатних питања, слободно се обратите нашој онлајн заједници. Ако желите да учествујете, можете погледати нашу страницу о [доприносима](contribute) или [отворите проблем са питањем](https://github.com/zammad/zammad-org/issues){target=\_blank} за смернице. ## Претпоставке о публици Документација подразумева да наши **корисници** поседују основно знање о употреби претраживача и концептима софтверског дизајна. Ово на пример значи да су функције описане до детаља, али не на нивоу како приступити падајућем менију. **Zammad администратор** треба додатно да поседује основно техничко разумевање радних токова и процеса комуникације у својој фирми. За инстанце које сами хостују, **администратори система** такође треба да буду упознати са основама администрације Linux система. Приступ систему који хостује (нпр. путем SSH) и администраторске дозволе се подразумевају. ## Садржај Циљ документације да садржи информације о: * Начину коришћења Zammad-а * Како управљати Zammad-ом као администратор (нпр. поставка након инсталације, подешавања, конфигурација функција) * Различити начини како инсталирати Zammad * Додатни водичи уколико је неопходна конфигурација система (за хостовање) и/или конфигурација сервиса трећих лица. У зависности од **нивоа детаља**, неопходно је узети у обзир [претпоставке о публици](#audience-assumptions). Управо из разлога зато што је један од циљева Zammad-а да буде интуитиван и прилагођен кориснику, није неопходно објашњавати сваки посебан клик мишем. Међутим, важни кораци морају бити укључени. Читаоци би требало да постигну своје циљеве што брже и једноставније без потребе да пуно читају. С обзиром да документација не може да покрије апсолутно све (иначе би садржала саме детаље кôда), неопходно је узети у обзир значајност информације. Уколико недостају делови који се односе на уобичајене случајеве коришћења, требало би их укључити у документацију. ## Стил и правила Следећи одељак покрива опште ствари у вези писања документације. Након овога можете прећи на одељак са неким [примерима](#examples) садржаја. ### Основе * Документација је написана у Markdown језику описа страна. Изворне датотеке имају `.md` екстензију. * Систем користи [Vitepress](https://vitepress.dev/){target=\_blank} за прављење веб сајта. * Изворни језик датотека је амерички енглески. * Преводи документације се врше преко Weblate апликације, погледајте [одељак о преводима](contribute#превод) на страници о доприносима за више информација. ### Стил * Користите кратке и јасне реченице, дајући предност информацијама у односу на сложеност. * Користите реченичну капитализацију за наслове страна и поднаслове. Великим словом пишите прву реч и прво слово сваке властите именице (нпр. Zammad, Elasticsearch, Docker, GitLab) и акронима (SLA, SSO, API, JSON, итд.). * Одвојите путање навигације са `>` сепаратором и користите форматирање у курзиву, нпр. *Подешавања > Канали > Ћаскање*. * Користите назначавање изворног кода да бисте нагласили секције о програмском језику. * Користите [оквире са информацијама, саветима и упозорењима](#custom-boxes) по потреби. * Користите [одељак са детаљима](#прилагођени-оквири) када садржај можда није релевантан за све читаоце и има потенцијал да прекине ток мисли). * Уколико је могуће, користите иконице за важне елементе корисничког интерфејса као што су ::+:: и ::x:: (погледајте [примере](#текст-и-интерфејс) испод). * Користите ознаке тастера као што су \[\[ctrl]] и \[\[x]] да означите притисак на тастатури (погледајте [примере](#text-and-ui) испод). * Убаците снимке екрана по потреби. Пожељан начин додавања снимака екрана из Zammad-а је њиховим аутоматским креирањем [коришћењем Cypress апликације](https://github.com/zammad/zammad-org?tab=readme-ov-file#automatic-screenshots-cypress){target=\_blank}. Ово доприноси лакшем одржавању документације јер ће свежи снимци екрана бити аутоматски направљени сваки пут кад се генерише документација. Обратите пажњу да је начин коришћења Cypress-а изван обима ове документације. * Приложите упутства корак по корак са јасним објашњењима. * Користите примере или сценарије да илуструјете концепте. * Убаците релевантне слике или дијаграме по потреби. * Дефинишите скраћенице када се први пут користе или их укључите у речник и убаците везу на њих. Нашироко коришћене и уобичајене скраћенице могу бити искључене из овог правила. * Ако сте у недоумици, ускладите се са постојећом документацијом. ### Конвенције Алати за прављење документације укључују аутоматске провере (linting) да би осигурали усклађеност са водичем кроз стил и основним правилима за Markdown садржај. Да бисте проверили усклађеност, покрените `pnpm lint` за проверу. Неки уобичајени проблеми се чак могу и аутоматски поправити покретањем `pnpm lint:fix`. Обратите пажњу да покренете проверу пре слања ваших измена. У супротном, генерисање документације неће бити успешно. Провере користе нека уобичајена правила која можете пронаћи у [званичном репозиторију](https://github.com/DavidAnson/markdownlint/blob/v0.32.1/README.md#rules--aliases){target=\_blank}. Нека важнија и прилагођена правила су излистана испод. * Дужина линије у изворној датотеци не би требало да прелази 120 карактера за стандардан текст. Обратите пажњу да убаците ред пре постизања ове границе. Визуелни индикатор у вашем уреднику текста вам може помоћи. Ово се не односи на специјалан садржај као путање на снимке екрана и дугачке везе. * Више узастопних празних редова није дозвољено. * Празни редови пре и после наслова и блокова кôда су обавезни. * Користите ` ``` ` (машинске апострофе) за ограничавање блокова кôда, пратећи их са ознаком језика, нпр. `ruby` или `sh`. Уколико у питању није конкретан језик, користите `plain`. * Користите `-` за листу са тачкама (неуређене листе) као што је ова. * За јасну разлику између **подебљаног** и текста у *курзиву*, користите `_` око текста у курзиву и `**` за подебљавање (нпр. `_курзив_` односно `**подебљано**`). * Вишеструки наслови са идентичним садржајем нису дозвољени. * Сваки документ мора имати само једно `h1` заглавље као наслов. * Резолуција снимака пуног екрана за *мобилни приказ* je 400x867 пиксела. * Резолуција снимака пуног екрана за *основни приказ* je 1920x1080 пиксела. Поред `pnpm lint`, репозиторијум користи [Vale](https://vale.sh/){target=\_blank} за лингвистичку проверу текста. Vale проверава доследно писање назива брендова (нпр. GitHub, GitLab, Elasticsearch), означава непожељне изразе и примењује правила из листе речи. Покреће се аутоматски над припремљеним (staged) фајловима када направите commit, као и у CI-ју упоредо са Markdownlint задатком. Да бисте га покренули ручно, користите `pnpm vale`. ### Примери #### Текст и интерфејс | Тип | Истицање у документацији | Markdown синтакса | |--------------------------------------|-------------------------------|---------------------------------| | Наслови дугмића | `Пријава` | `` `Пријава` `` | | Поља, елементи интерфејса, менији | **Назив** | `**Назив**` | | Навигационе путање | *Подешавања > Канали > Имејл* | `_Подешавања > Канали > Имејл_` | | Путање датотека и директоријума | `/opt/zammad` | `` `/opt/zammad` ``. | | Примери вредности за подешавања | `` | `` `` `` | | Примери вредности за API захтеве | `{ticket id}` | `` `{ticket id}` `` | | Конзолне вредности, портови, кључеви | `9200` | `` `9200` `` ` | | Пречице на тастатури | [[x]] |`\[\[x]]` | | Дугме за додавање | ::+:: |`::+::` | | Дугме за брисање | ::x:: |`::x::` | | Дугме за мени радњи | ::a:: |`::a::` | | Дугме за копирање текста | ::c:: |`::c::\` | #### Структура наслова Свака страна документације мора да поседује наслов највишег нивоа (нпр. `# Наслов`). Нижи нивои треба да садрже најмање два одељка. Уколико постоји само један одељак, размотрите да га припојите садржају вишег нивоа. Пример: `# Наслов стране` `## Одељак 1` `### Одељак 1.1` `### Одељак 1.2` `## Одељак 2` #### Одељак са значком Наслов овог одељка користи значку „упозорења”. Доступне су и остале значке, погледајте . **Начин коришћења:** ::: details ```md Одељак са значком ``` ::: #### Прилагођени оквири ::::: info Ово је информациони оквир. **Начин коришћења:** :::: details ```md ::: info Ово је информациони оквир. ::: ``` :::: ::::: ::::: tip Ово је савет. **Начин коришћења:** :::: details ```md ::: tip Ово је савет. ::: ``` :::: ::::: ::::: warning Ово је упозорење. **Начин коришћења:** :::: details ```md ::: warning Ово је упозорење. ::: ``` :::: ::::: ::::: danger Ово је упозорење на опасност. **Начин коришћења:** :::: details ```md ::: warning Ово је упозорење на опасност. ::: ``` :::: ::::: :::: details Ово је одељак са детаљима. **Начин коришћења:** ```md ::: details Овај садржај је приказан у проширеном стању. ::: ``` :::: #### Листе дефиниција Први термин : Ово је дефиниција првог термина. Други термин : Ово је дефиниција другог термина. : Ово је додатна дефиниција другог термина. **Начин коришћења:** ::: details ```md Први термин : Ово је дефиниција првог термина са додатном линијом текста. ``` ::: #### Наглашавање са оквирима За наглашавање различитих опција или варијанти, можете користити кућице. Садржај се дефинише путем frontmatter одељка у Markdown датотеци, видите следећи пример (односи се на кућице изнад): ```yml features: - icon: 🛠️ title: Увек једноставан и сведен details: Lorem ipsum... link: https://zammad.com linkText: Ово је линк target: _blank - icon: src: /assets/logo.svg title: Још једна „кул” функција details: Lorem ipsum... link: https://zammad.com - icon: dark: /assets/logo-flat-dark.svg light: /assets/logo-flat-light.svg title: Још једна „кул” функција details: Lorem ipsum... link: https://zammad.com ``` За уметање унутар садржаја стране, једноставно унесите `` референцу где желите да се појави. #### Слике специфичне за тему Да бисте ограничили одређене слике на једну тему, можете доделити CSS класу `.dark-only` или `.light-only` одговарајућој слици: ```md ![Само за тамну изглед](/assets/logo-flat-dark.svg){.dark-only} ![Само за светли изглед](/assets/logo-flat-light.svg){.light-only} ``` ![Само за тамни изглед](/assets/logo-flat-dark.svg){.dark-only width=240} ![Само за светли изглед](/assets/logo-flat-light.svg){.light-only width=240}