> What does a clean documentation look and feel like? Documentation is content and should be treated as one. It should take technical concepts and convey them to the readers as clear as possible. This mean staying acurate and detailed in the technicalities, but also considering that it should be content that is easy to read and understand. This can mean being less "rigid" in the tone, throwing in metaphors, and a joke once in a while is welcomed. At the same time, documentation should follow a rigid structure and formatting- so that every page looks and feels complete and consistent. --- # Structure Guideline - The File Name is used as the main title of the page, so we don't need a duplicate title using H1. - Top level Folders should contain a `Overview` file for index page # Document Guideline - Try to link relevant documents in-line and at end of page in next steps - each page should start with a `>` element which is a statement/question which describes why the page exists. this should be followed by a paragraph description, ending with a line break. - the upcoming documentation should be separated from the descriptive paragraph with a ``---`` to justify the start of the documentation - Use inline linking in every document. Follow the idea of Wikipedia- where the first time a certain concept is mentioned on the page, it is linked to the specific document. After a page is linked once in a document, it does not need to link it more than once per page. - At the end of each page, we should have a **Read Next** section with links to 2-4 relevant pages. When possible, include pages from Guides and FAQ. - from there use headers to divide ideas using this guideline H1 (#): The Page Title. Use only once at the very top. It should be a noun or a clear action (e.g., "Installation" or "API Reference"). H2 (##): Major Sections. These should be scannable. If a user scrolls quickly, they should understand the workflow just by reading these. H3 (###): Sub-steps or Details. Use these for specific configurations or "Notes" within a section. Avoid H4 and below: If you need four levels of headers, your page is likely too long. Break it into a new note. # Formatting Guideline A "modern" look relies on consistent UI patterns that mimic high-end documentation sites. ## Callouts Obsidian supports **Callouts**, which are essential for highlighting info without breaking the flow. > [!TIP] Use tips for "nice-to-know" shortcuts. > [!IMPORTANT] Use these for critical requirements or warnings. ## Code Blocks Always specify the language for syntax highlighting. - **Inline:** Use `backticks` for file names, variables, or short commands. - **Blocks:** Use triple backticks with the language name (e.g., ` ```python `) ## Emphasis - **Bold:** Use for UI elements (e.g., "Click the **Submit** button") - **Italics:** Use sparingly, primarily for introducing new technical terms for the first time ## Special Callouts Use these exact callouts on the top of the page for product specific documentation: > [!info] Available on SPX Production or Broadcast license [Learn more](https://beta.spx.graphics/contact) >[!info] Available only on SPX Broadcast license. [Learn more](https://beta.spx.graphics/contact) # Resources For obsidian flavored markdown refer to this website. https://help.obsidian.md/obsidian-flavored-markdown