FAQ Creation Rules

Delete after old rules: ClickUp

 

Structure

  1. One article covers one problem/question.

  2. Title describes a problem or asks a question;

  3. Optimal title length is 60 symbols. Max length is 100 symbols;

  4. 1 sentence = 1 step: Do > This > Where;

  5. After each instruction list, add a sentence describing the result — "The text is now added", "The link is now created", etc;

  6. Use a numbered list for steps that must be followed in order;

  7. Use a bulleted list for unordered items and options to choose from;

  8. Use lists for steps and items:

    "Numbers" list type — used for sequential steps, such as instructions where order matters;
    "Bullets" list type — used for options or items that don't follow a strict sequence;

    Each list item ends with a semicolon; the last item ends with a period — unless the item already ends with a punctuation mark, e.g. "?".

  9. Link to other FAQ articles only within the article's own context;

  10. Never suggest doing something extra (customizing, configuring, changing) without linking to the FAQ article that explains it;

  11. Use Note blocks sparingly — up to 3 per article, never back-to-back. More than that (or notes in a row) means the content needs restructuring or splitting.

 

Formatting

  1. Write navigation paths in italic with spaces around the arrow (e.g. Menu → Submenu → Page). Do not use italic in other places;

  2. Use bold text only to highlight important words, short phrases or section;
  3. Use icons to mention buttons. If the button has a text label, describe it using that label. Never use images;
  4. Verify icon names [icon="icon-name"] match the actual interface — check the feature's own FAQ article for the correct icon class;

 

Images & Videos

  1. Width: 100% — when the overall context is important for understanding the image: navigation, several connected sections, a wide table, the arrangement of elements on the page, or small details.
    535px — when the image shows one self-contained element, such as a modal window, form, message, or small interface fragment that remains clear and readable when reduced.

  2. Width: 100% — if image has navigation, several connected sections, small details.
    Width: 535px — when the image shows one important element: a popup, or focuses on a specific part of the interface.

  3. Should have short descriptive alt (relative to it);

  4. Should not contain sensitive data;

  5. Do not add a "Preview" or "Ads" label above images or videos.

  6. Do not add a "Preview" or "Ads" label above images or videos — use "Example image" or "Example video" instead.

 

Language & Tone

  1. Never use "click" — always use "press" and "select";
  2. Never use "e.g." — always use "for example";
  3. Avoid "please";

  4. Check all links in FAQ;

  5. Add translations, then review for accuracy.
  6. If an FAQ article mentions a problem or a feature related to another FAQ article, add a link to it in th "Related articles" block;

  7. Should be 10 aliases for 1 FAQ (including all language variations). Aliases shouldn't look artificial.

  8. Check all links in FAQ (its canonical, no broken, no 404).

 

Content Integrity

  1. For every noun or action in the article, check if it matches any other FAQ article title — read the article, extract all features, technical terms, and action names, then search the saved FAQ articles by title — if a match exists, add a link to that article.
  2. Always check for terms explained in the articles https://site.pro/faq/55608/ and https://site.pro/faq/3820/ — if a match exists, add a link to that article.

 

References

  1. SPML syntax guide: https://spml.site.pro