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

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

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

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

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

The documentation assumes that users have a basic understanding of how to use web browsers and are familiar with common software design concepts. This means, for example, that features are described in detail, but not to the level of explaining how to open a dropdown menu.

The Zammad administrator should also have a basic technical understanding and be familiar with the workflows and communication processes within their company.

For self-hosted instances, system administrators should also be familiar with Linux system administration basics. Access to the host system (e.g. via SSH) and administrative permissions are taken for granted.

Садржај

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

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

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

Due to the fact that a documentation can't cover everything (otherwise it would be on a code-like detail level), the relevance has to be considered too. If parts with a common use case are missing, it should be intended to include them in.

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

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

Основе

• Документација је написана у 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 пиксела.

Примери

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

Type	Highlighting in documentation	Markdown syntax
Labeled buttons	Sign in	`Sign in`
Fields and UI elements	Name	**Name**
Locations/paths	Settings > Channels > Email	_Settings > Channels > Email_
Keyboard shortcuts	x	[[x]]
Add button	＋	::+::
Delete button	✕	::x::
Action menu	︙	::a::
Copy to clipboard button		::c::

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

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

Пример:

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

## Одељак 1

### Одељак 1.1

### Одељак 1.2

## Одељак 2

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

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

Usage:

Details

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

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

INFO

This is an info box.

Usage:

Details

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

TIP

This is a tip.

Usage:

Details

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

WARNING

This is a warning.

Usage:

Details

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

DANGER

This is a dangerous warning.

Usage:

Details

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

Details

This is a details block.

Usage:

::: details
Овај садржај је приказан у проширеном стању.
:::

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

Први термин tag1

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

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

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

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

Usage:

Details

Први термин <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 /> референцу где желите да се појави.

Theme Specific Images

To target specific image assets to a single theme, you can assign .dark-only or .light-only CSS class to the corresponding image:

![Dark only image](/assets/logo-flat-dark.svg){.dark-only}
![Light only image](/assets/logo-flat-light.svg){.light-only}