Водич кроз стил и садржај

Овај водич вам пружа преглед садржаја Zammad документације, као и упутства за форматирање и стилизовање текста ради јасноће и читљивости.

Први одељци садрже уопштене информације и правила. Одељак са примерима је на крају.

Уколико имате додатних питања, слободно се обратите нашој онлајн заједници. Ако желите да учествујете, можете погледати нашу страницу о доприносима или отворите проблем са питањем за смернице.

Претпоставке о публици

Документација је написана у стилу који подразумева да наши корисници поседују основно знање о употреби претраживача и концептима софтверског дизајна. Ово на пример значи да су функције описане до детаља, али не на нивоу како приступити падајућем менију.

Zammad администратор треба додатно да поседује основно техничко разумевање радних токова и процеса комуникације у својој фирми.

За инстанце које сами хостују, администратори система такође треба да буду упознати са основама администрације Linux система. Приступ систему који хостује (нпр. путем SSH) и администраторске дозволе се подразумевају.

Садржај

Циљ документације да садржи информације о:

• Начину коришћења Zammad-а
• Како управљати Zammad-ом као администратор (нпр. поставка након инсталације, подешавања, конфигурација функција)
• Различити начини како инсталирати Zammad
• Додатни водичи уколико је неопходна конфигурација система (за хостовање) и/или конфигурација сервиса трећих лица.

У зависности од нивоа детаља, неопходно је узети у обзир претпоставке о публици. Управо из разлога зато што је један од циљева Zammad-а да буде интуитиван и прилагођен кориснику, није неопходно објашњавати сваки посебан клик мишем. Међутим, важни кораци морају бити укључени. Читаоци би требало да постигну своје циљеве што брже и једноставније без потребе да пуно читају.

С обзиром да документација не може да покрије апсолутно све (иначе би садржала саме детаље кôда), неопходно је узети у обзир значајност информације. Уколико недостају делови који се односе на уобичајене случајеве коришћења, требало би их укључити у документацију.

Стил и правила

Следећи одељак покрива опште ствари у вези писања документације. Након овога можете прећи на одељак са неким примерима садржаја.

Основе

• Документација је написана у Markdown језику описа страна. Изворне датотеке имају .md екстензију.
• Систем користи Vitepress за прављење веб сајта.
• Изворни језик датотека је амерички енглески.
• Преводи документације се врше преко Weblate апликације, погледајте одељак о преводима на страници о доприносима за више информација.

Стил

• Користите кратке и јасне реченице, дајући предност информацијама у односу на сложеност.
• Наслови страна и поднаслови: започните великим словом све речи осим изузетих (погледајте title case).
• Одвојите путање навигације са > сепаратором и користите форматирање у курзиву, нпр. Подешавања > Канали > Ћаскање.
• Користите назначавање изворног кода да бисте нагласили секције о програмском језику.
• Користите оквире са информацијама, саветима и упозорењима по потреби.
• Користите одељак са детаљима када садржај можда није релевантан за све читаоце и има потенцијал да прекине ток мисли).
• Уколико је могуће, користите иконице за важне елементе корисничког интерфејса као што су ＋ и ✕ (погледајте примере испод).
• Use key markup like ctrl and x to highlight a key press (see examples below).
• Убаците снимке екрана по потреби. Пожељан начин додавања снимака екрана из Zammad-а је њиховим аутоматским креирањем коришћењем Cypress апликације. Ово доприноси лакшем одржавању документације јер ће свежи снимци екрана бити аутоматски направљени сваки пут кад се генерише документација. Обратите пажњу да је начин коришћења Cypress-а изван обима ове документације.
• Приложите упутства корак по корак са јасним објашњењима.
• Користите примере или сценарије да илуструјете концепте.
• Убаците релевантне слике или дијаграме по потреби.
• Дефинишите скраћенице када се први пут користе или их укључите у речник и убаците везу на њих. Нашироко коришћене и уобичајене скраћенице могу бити искључене из овог правила.
• Ако сте у недоумици, ускладите се са постојећом документацијом.

Конвенције

The documentation stack includes automated checks (linting) to ensure compliance with the style guide and common rules for Markdown files. To check if your changes are compliant, run pnpm lint to perform the check. Some of the recognized problems can be even fixed automatically by running pnpm lint:fix. Make sure to run the check before committing your changes. Otherwise, the build of the documentation will fail.

Провере користе нека уобичајена правила која можете пронаћи у званичном репозиторију. Нека важнија и прилагођена правила су излистана испод.

• Дужина линије у изворној датотеци не би требало да прелази 120 карактера за стандардан текст. Обратите пажњу да убаците ред пре постизања ове границе. Визуелни индикатор у вашем уреднику текста вам може помоћи. Ово се не односи на специјалан садржај као путање на снимке екрана и дугачке везе.
• Више узастопних празних редова није дозвољено.
• Празни редови пре и после наслова и блокова кôда су обавезни.
• Користите ``` (машинске апострофе) за ограничавање блокова кôда, пратећи их са ознаком језика, нпр. ruby или sh. Уколико у питању није конкретан језик, користите plain.
• Користите - за листу са тачкама (неуређене листе) као што је ова.
• За јасну разлику између подебљаног и текста у курзиву, користите _ око текста у курзиву и ** за подебљавање (нпр. _курзив_ односно **подебљано**).
• Вишеструки наслови са идентичним садржајем нису дозвољени.
• Сваки документ мора имати само једно h1 заглавље као наслов.
• Резолуција снимака пуног екрана за мобилни приказ je 400x867 пиксела.
• Резолуција снимака пуног екрана за основни приказ je 1920x1080 пиксела.

Примери

Текст и интерфејс

Тип	Истицање у документацији	Markdown синтакса
Означени дугмићи	Пријава	`Пријава`
Поља и елементи	Назив	**Назив**
Путања/локације	Подешавања > Канали > Имејл	_Подешавања > Канали > Имејл_
Пречице на тастатури	x	[[x]]
Дугме за додавање	＋	::+::
Дугме за брисање	✕	::\x::
Дугме за мени радњи	︙	::\a::

Структура наслова

Свака страна документације мора да поседује наслов највишег нивоа (нпр. # Наслов). Нижи нивои треба да садрже најмање два одељка. Уколико постоји само један одељак, размотрите да га припојите садржају вишег нивоа.

Пример:

# Наслов стране

## Одељак 1

### Одељак 1.1

### Одељак 1.2

## Одељак 2

Одељак са значком прилагођен текст

Наслов овог одељка користи значку „упозорења”. Доступне су и остале значке, погледајте https://vitepress.dev/reference/default-theme-badge#usage.

Usage

Одељак са значком <Badge type="warning" text="прилагођен текст" />

Прилагођени оквири

INFO

Ово је информациони оквир.

Usage

::: info
Ово је информациони оквир.
:::

TIP

Ово је савет.

Usage

::: tip
Ово је савет.
:::

WARNING

Ово је упозорење.

Usage

::: warning
Ово је упозорење.
:::

DANGER

Ово је упозорење на опасност.

Usage

::: warning
Ово је упозорење на опасност.
:::

Details

Ово је одељак са детаљима.

Начин коришћења:

::: details Box title shown in collapsed state
Овај садржај је приказан у проширеном стању.
:::

Листе дефиниција

Први термин tag1

Ово је дефиниција првог термина.

Други термин tag1 tag2

Ово је дефиниција другог термина.

Ово је додатна дефиниција другог термина.

Usage

Први термин <Badge type="info" text="tag1" />
: Ово је дефиниција првог термина
  са додатном линијом текста.

Наглашавање са кућицама

За наглашавање различитих опција или варијанти, можете користити кућице.

🛠️

Увек једноставан и сведен

Lorem ipsum...

This is a link

Још једна „кул” функција

Lorem ipsum...

Још једна „кул” функција

Lorem ipsum...

Садржај се дефинише путем frontmatter одељка у Markdown датотеци, видите следећи пример (односи се на кућице изнад):

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

За уметање унутар садржаја стране, једноставно унесите <VPDocFeatures /> референцу где желите да се појави.