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

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

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

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

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

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

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

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

Садржај

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

• Начину коришћења 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. If parts with a common use case are missing, it should be intended to include them in the documentation.

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

The next sections cover general things to consider writing the documentation. After these you can find a section with some examples about how to format and structure the content.

Основе

• Документација је написана у Markdown језику описа страна. Изворне датотеке имају .md екстензију.
• Систем користи Vitepress за прављење веб сајта.
• Изворни језик датотека је амерички енглески.
• The translation of the documentation is done via Weblate, see translation section in the contribute page for more details.

Стил

• Користите кратке и јасне реченице, дајући предност информацијама у односу на сложеност.
• Наслови страна и поднаслови: започните великим словом све речи осим изузетих (погледајте title case).
• Одвојите путање навигације са > сепаратором и користите форматирање у курзиву, нпр. Подешавања > Канали > Ћаскање.
• Користите назначавање изворног кода да бисте нагласили секције о програмском језику.
• Користите оквире са информацијама, саветима и упозорењима по потреби.
• Користите одељак са детаљима када садржај можда није релевантан за све читаоце и има потенцијал да прекине ток мисли).
• If available, use icons for important UI buttons like ＋ and ✕ (see examples below).
• Убаците снимке екрана по потреби. Пожељан начин додавања снимака екрана из Zammad-а је њиховим аутоматским креирањем коришћењем Cypress апликације. Ово доприноси лакшем одржавању документације јер ће свежи снимци екрана бити аутоматски направљени сваки пут кад се генерише документација. Обратите пажњу да је начин коришћења Cypress-а изван обима ове документације.
• Приложите упутства корак по корак са јасним објашњењима.
• Користите примере или сценарије да илуструјете концепте.
• Убаците релевантне слике или дијаграме по потреби.
• Дефинишите скраћенице када се први пут користе или их укључите у речник и убаците везу на њих. Нашироко коришћене и уобичајене скраћенице могу бити искључене из овог правила.
• Ако сте у недоумици, ускладите се са постојећом документацијом.

Конвенције

Алати за прављење документације укључују аутоматске провере (linting) да би осигурали усклађеност са водичем кроз стил и основним правилима за Markdown садржај. Да бисте проверили усклађеност, покрените pnpm lint за покретање провере. Неки уобичајени проблеми се чак могу и аутоматски поправити покретањем pnpm lint:fix. Обратите пажњу да покренете проверу пре слања ваших измена. У супротном, генерисање документације неће успети.

The used linting has some built in rules which you can find in the official repository. Some important rules and customized ones are mentioned below.

• Дужина линије у изворној датотеци не би требало да прелази 120 карактера за стандардан текст. Обратите пажњу да убаците ред пре постизања ове границе. Визуелни индикатор у вашем уреднику текста вам може помоћи. Ово се не односи на специјалан садржај као путање на снимке екрана и дугачке везе.
• Више узастопних празних редова није дозвољено.
• Празни редови пре и после наслова и блокова кôда су обавезни.
• Use ``` (backticks) for fenced code blocks, followed by a mandatory language tag, e.g. ruby or sh. If no language is applicable, use plain.
• Use - for bullet point lists (unordered lists) like this one.
• To easily distinguish between bold and italics, use _ around the text for italics and ** for bold (e.g. _italic_ vs. **bold**).
• Multiple headings with the same content are not allowed.
• Each document must have exactly one h1 heading as title.
• Resolution of manual full page screenshots for mobile view is 400x867 pixels.
• Resolution of manual full page screenshots for desktop view is 1920x1080 pixels.

Examples

Text and UI

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::

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

Every documentation file must include exactly one title on top level (like # Title). Levels below should always contain at least two sections. If only one section exists, consider merging it with the higher-level content.

Пример:

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

## Одељак 1

### Одељак 1.1

### Одељак 1.2

## Одељак 2

Section with Badge custom text

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

Usage

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

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

INFO

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

Usage

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

TIP

Ово је савет.

Usage

::: tip
This is a tip box.
:::

WARNING

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

Usage

::: warning
This is a warning box.
:::

DANGER

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

Usage

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

Details

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

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

::: details Box title shown in collapsed state
This is the content shown in the expanded state.
:::

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

Први термин tag1

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

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

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

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

Usage

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

Highlighting with Boxes

To highlight different options or variants, clickable boxes can be used.

�Ÿ›��

Simple and minimal, always

Lorem ipsum...

This is a link

Another cool feature

Lorem ipsum...

Another cool feature

Lorem ipsum...

The definition of the content is done via frontmatter, see following example (reflects the boxes above):

features:
  - icon: 🛠️
    title: Simple and minimal, always
    details: Lorem ipsum...
    link: https://zammad.com
    linkText: This is a link
    target: _blank
  - icon:
      src: /assets/logo.svg
    title: Another cool feature
    details: Lorem ipsum...
    link: https://zammad.com
  - icon:
      dark: /assets/logo-flat-dark.svg
      light: /assets/logo-flat-light.svg
    title: Another cool feature
    details: Lorem ipsum...
    link: https://zammad.com

To place it within the content area, simply insert the reference <VPDocFeatures /> at the point where it has to be rendered.