HelpFIT
Go to navigation

Contributing

HelpFIT is built using PagesFIT, AsciiDoc, and a modified version of the course-pages generator.

FAQ

I found a bug
You can use one of two methods:
  1. Report the bug (see Creating an Issue) using the Report a bug button at the top of the page.
  2. Suggest a change via your own merge request.
I have a suggestion for improvement
The same as reporting a bug.
I want to add my own guide

Currently, HelpFIT policy is to present service guides exclusively under the ICT department, ensuring their validity and correctness. All persons associated with FIT CTU can use PagesFIT, which powers this site. Anyone (e.g., a department or research group) may create their own pages fully under their own responsibility.

Naturally, you can contact the ICT department via the helpdesk form for further steps. Alternatively, escalate your request through your department or group head.

Conventions

Recommended tools

The following tools are recommended for work:

Structure

The structure of guides follows these rules:

  • Guides (and their files) are separated into /cs and /en folders at the repository root depending on language.
  • Each guide is placed in its own directory named after the guide.
  • Each guide contains an entry page index.adoc, always located at the root of the guide directory.
  • If a guide requires a FAQ page, it is written in a separate faq.adoc file.
  • If a guide consists of multiple thematic parts, each topic has its own subdirectory.
  • Images and other files are stored in a /media folder inside the guide directory.
  • If the same image is used in multiple places, a symbolic link is created pointing to the original image.
Example repository structure
help.fit.cvut.cz
β”œβ”€β”€ cs/
β”‚   └── courses/
β”‚       β”œβ”€β”€ index.adoc
β”‚       β”œβ”€β”€ faq.adoc
β”‚       β”œβ”€β”€ content/
β”‚       β”‚   β”œβ”€β”€ index.adoc
β”‚       β”‚   β”œβ”€β”€ news.adoc
β”‚       β”‚   └── media/
β”‚       β”‚       β”œβ”€β”€ icon.png
β”‚       β”‚       └── diagram-cs.png
β”‚       β”œβ”€β”€ processes/
β”‚       β”‚   └── index.adoc
β”‚       └── media/
β”‚           └── logo.png
β”‚
β”œβ”€β”€ en/
β”‚   └── courses/
β”‚       β”œβ”€β”€ index.adoc
β”‚       β”œβ”€β”€ faq.adoc
β”‚       β”œβ”€β”€ content/
β”‚       β”‚   β”œβ”€β”€ index.adoc
β”‚       β”‚   β”œβ”€β”€ news.adoc
β”‚       β”‚   └── media/
β”‚       β”‚       β”œβ”€β”€ icon.png
β”‚       β”‚       └── diagram-en.png
β”‚       β”œβ”€β”€ processes/
β”‚       β”‚   └── index.adoc
β”‚       └── media/
β”‚           └── logo.png
β”‚
β”œβ”€β”€ .attributes.adoc
└── .shared-content.adoc

Naming

General rules for naming files and folders:

  • English naming
  • Lowercase
  • No spaces
  • Words separated by hyphens (-)
  • English and Czech versions of guides share the same name

Naming of guides:

  • The entry page is always named index.adoc.
  • Other pages should be named to best reflect their content.
  • FAQ page (frequently asked questions)

Naming of images and other media:

  • The name should describe the content of the media.
  • Media with Czech content end with -cs, e.g. courses-architecture-fitpages-cs.png or courses-architecture-fitpages-cs.drawio, and are stored in the Czech version of the guide.
  • Media with English content end with -en, e.g. courses-architecture-fitpages-en.png or courses-architecture-fitpages-en.drawio, and are stored in the English version of the guide.
  • If the media has no language-specific content, the suffix is omitted, e.g. redundant.png.
  • If no bilingual version exists, a symbolic link is created pointing to the existing media with the same name as the existing file [1].
  • Image series are numbered starting from one without a leading zero, e.g. image-1-cs.png or image-9-cs.png.

Media

Rules for working with media:

  • Media are stored according to the structure conventions.
  • Media are named according to the naming conventions.
  • White-mode screenshots with Czech localization are preferred for Czech guides, and English localization for English guides.
  • PNG is the preferred image format.
  • It is recommended to capture full-screen screenshots.
  • A fictional user Kevin Flynn (flynnkev@cvut.cz) is used as the sample user.

  • If a QR code is needed, the following can be used:

    qr example

To improve generator performance, reduce page size, and improve usability, media compression is required. [2] Recommended width is 1,200 px, but individual cases and readability must be considered. Maximum image size should ideally stay within tens of kB. ImageMagick is recommended. See the following commands.

Image compression using ImageMagick
Windows / Linux
convert <filename> \
    -density 72 \
    -resize <size> \
    -alpha off \
    +dither \
    -colors 256 \
    -depth 8 \
    -strip \
    -define png:compression-filter=5 \
    -define png:compression-level=9 \
    -define png:compression-strategy=1 \
    -define png:exclude-chunk=all \
    -interlace none \
    <filename>
MacOS
convert <filename> \
  -density 72 \
  -resize <size> \
  -alpha on \
  +dither \
  -strip \
  -define png:compression-filter=5 \
  -define png:compression-level=9 \
  -define png:compression-strategy=1 \
  -define png:exclude-chunk=all \
  -interlace none \
  <filename>

The upload location must be under ICT department control. If a file is too large (> 10 MB), prefer uploading it to GitLab using Git LFS, or contact the ICT department via the helpdesk form.

AsciiDoc

Rules for writing AsciiDoc files:

  • Attribute definitions, include::, :toc:, :imagesdir: macros, etc. must be placed at the top of the file.
  • Each page must have exactly one title – first-level heading [3]
  • Headings should avoid phrases like β€œHow to log in”. Instead, prefer β€œLogin”.
    • Similarly, avoid sections like β€œAbout the system” as the first section; describe the system directly in the opening paragraphs.
  • Two blank lines before headings, one blank line after headings.
  • Each sentence should be on a separate line. [4]

    • If a list item is an addition to the main sentence, the addition may be placed on the same line if it is relatively short:

      * This is the main sentence, which may be longer. This is a shorter addition.
* This is another main sentence, which is long.
  This is a longer addition explaining the main sentence.
* This is another sentence.

    • If a bullet point spans multiple lines, the sentence is indented to the same level as the first sentence at that level:

      * First sentence.
  Second sentence.
** Third sentence.
   Fourth sentence.
* Fifth sentence.
  • List items are written without blank lines between individual items.
  • If a list item is:
    • an instruction that the user must perform, a period is written at the end of the sentence.
    • only a statement of some fact, no period is written (in case an image follows, a colon may also be used)
  • Each file must end with a blank line.
  • Use the :imagesdir: attribute for images.
  • Dashes (not hyphens) should be written using -- or the Unicode character –.
  • Links:
    • should include a descriptive label.
    • internal links use xref:, e.g. xref:conventions[Conventions]
    • cross-doc links use xref:, e.g. xref:./rooms/index.adoc#labels[Labels]
    • external links use Example+
    • for attribute-based URLs, use link: for readability, e.g. link:{example-site-url}[Example]
  • Quotes should use either "…​" or Unicode quotation marks.
  • Recommended macros are:
    • btn:[], looking as Button
    • menu:[], looking as File › Save › Save As
    • kbd:[], looking as Ctrl+S
  • When using the include:: and xref: macros, the user may encounter an error during HTML generation. This error does not cause the build to fail, but it may slow down the build process. This is a known issue described in Courses FAQ
  • To prevent formatting, for example in code blocks, use the simple +, the triple +++, or the macro pass:[]. You can also use the backslash \, but only if the code is readable enough.
  • Try to avoid phrases like …​ you can find here or …​ see this page.

Variables and Shared Content

Storing a value in a variable is useful, for example, for values that may change in the future.

Caution:

Global variables take precedence in case of name collisions and do not allow macros to be evaluated.

All variables are defined in the .attributes.adoc file located at the root of the file structure and must be included in a file using the include::./attributes.adoc[] macro to be used. This allows the editor to validate whether a variable exists or is even used. Their use is strongly preferred for expressions used across guides.[5]

However, variables do not support multi-line content. For this purpose, it is recommended to use the .shared-content.adoc file, which is also defined globally at the root of the file structure. Here’s how to work with multi-line content:

.shared-content.adoc

Write the content you want to share across files into this file and wrap it in a tag:

// tag::outlook-recommendation[]
For full compatibility, we recommend using *Microsoft Outlook*.
// end::outlook-recommendation[]
Usage in a guide

In the guide, write the following in the include:: macro:

include::../.shared-content.adoc[tag=outlook-recommendation]

Common expressions

To ensure consistency across guides and follow the DRY principle, variables and common expressions are used.

Abbreviations

For well-known names within the CTU environment (e.g., names of departments), the use of abbreviations is preferred. If the author considers it necessary to mention the full name, it is recommended to provide both the full name and the abbreviation by which it will be referred to thereafter.

Names that are commonly referred to by their abbreviations:

  • Instead of Czech Technical University in Prague, only CTU may be used.
  • Instead of Faculty of Information Technology, only FIT CTU may be used.
  • Instead of Computing and Information Center of the Czech Technical University in Prague, only VIC CTU may be used.
  • and so on.

Frequent expressions

These recommendations define preferred phrasing:

  • Log in using your CTU username and password.
  • …​ in the form <username>@fit.cvut.cz
    • Emphasize the domain to avoid confusion with cvut.cz.
  • Use e-mail instead of email or mail.
  • Phone numbers within the faculty should use the format +420 12345 6789, with a space separating the last four digits. [6]

Addressing the reader

It is recommended to avoid addressing the reader directly and instead use an indefinite subject (or user) in the sentence and the passive voice. That is, instead of If you use …​, write When using …​.

If addressing the reader is necessary, prefer pronoun forms, e.g., your instead of Your (i.e., lowercase β€œy”).

Global variables

Storing values in variables is useful for values subject to change.

Caution:

Global variables take highest precedence in case of conflicts and prevent macro evaluation.

Global variables are defined in .attributes.adoc and must be included via include::./attributes.adoc[]. The editor can validate whether a variable exists and whether it is actually used. Their use is strongly recommended for values used across multiple guides. [7]

Git

Rules for working with the Git version control system:

  • Add the name of the guide the change applies to as a prefix. For example, projectsfit: Fix typo
    • If you are making changes to multiple guides at once or if the change affects the entire project, use the prefix meta
  • Write the title of the commit message in the imperative, with a capital letter at the beginning, no period at the end, and preferably within 69 characters (max 80 characters), e.g., meta: Add README, not meta: Added README
    • You can add a link to an issue at the end of the message in the form #ID, where ID is the issue number that the commit addresses. For example: Add new printer (#123)
  • When naming branches, it is recommended to use a prefix with the issue number that the branch addresses. For example, 123-fix-link
  • Set your Git user.name. You can find instructions, for example, in the documentation at GitHub Docs
  • Use merge requests as much as possible: merge requests.
  • If you are creating a new guide, you can perform a squash during the merge. Otherwise, it is recommended to preserve individual commits, e.g., by using a semi-linear history

Other conventions

Other rules that do not fit into previous categories:

  • If an admonition block conflicts with a toc, follow the instructions for handling conflicts
  • To emphasize a word or sentence, the author can use bold or italics
  • For FAQs, always use a separate file titled Frequently Asked Questions and named faq.adoc; use the qanda macro.
  • It is recommended that guides include a Support section listing contact information for who to reach out to in case of problems or suggestions for improvement.[8]``
  1. If a bilingual version appears in the future, it is easier to check the suffix and the language folder where the media is stored and then replace it. ↩
  2. Otherwise a single page may reach several MB. ↩
  3. = Title in AsciiDoc. ↩
  4. Do not wrap text at a fixed character width. ↩
  5. Typically for links. ↩
  6. The last four digits are the internal extension number. ↩
  7. Typically for links. ↩
  8. This is not necessarily the IT department. ↩