IxDF Developer Docs

Appearance

Meta ​

This document describes how to write docs.

Scope ​

Tech Docs written by developers for developers (with some rare exceptions that are explicitly highlighted and marked by the 👠emoji).

These docs should not overlap/repeat/replace none of these sources:

  • IxDF handbook course
  • official documentation of tools, libraries, etc. (synopsis is not considered as duplication)
  • company docs, stored on Dropbox

Rules ​

1. Be clear and concise ​

Laravel documentation is a good example of how to write docs.

Optionally, start by "TL;DR" section for someone who reads this doc not for the first time and needs a reminder.

2. Single source of truth ​

Do not duplicate information. Link docs instead.

3. Know your reader ​

The Majority of docs in this directory created for developers (seniors). But sometimes we should like to share info with non-technical staff. In such cases, a good practice to extract such info into a separate document and do not mix technical and non-technical content. This way you will keep documents readable for all potential readers.

4. Focus on "WHY?" ​

It’s important to explain why we have made this or that decision, for the following reasons:

  • Easier to remember a rule/convention when you know underlying reasons
  • Easier to follow a rule/convention when you know underlying reasons
  • Easier to change the rule/convention when you know underlying reasons

5. Keep the Verbosity vs. Flexibility balance ​

Verbosity vs. Flexibility: when write docs, try to describe:

  • high-level overview
  • important domain details
  • important technical details

Keep the rest for the codebase: code and tests. When you write docs, imagine that sharing the doc is an act of knowledge transfer for a just hired senior developer who will work with this code. Do not try to document everything: we hire smart people 🦄, they will figure out the rest!

Hacks MUST be documented in the codebase, not in the docs.

6. Requirements Language ​

The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in our documents are to be interpreted as described in RFC 2119

Formats (text vs video) ​

Video documentation complements our existing text-based documentation. We are currently in the experimental phase, evaluating the most effective use cases for video content. The video documentation is stored on Dropbox in the IxDF - Development / Video Documentation folder.

When to Use Video Documentation ​

  1. Content Longevity: Prioritize topics that change infrequently, as updating videos is more resource-intensive than text.

  2. Hierarchy:

    • Text documentation takes precedence over video when content conflicts.
    • Use videos to supplement, not replace, text documentation.

  3. Visual Complexity:

    • Choose video for topics that are challenging to explain in text alone.
    • Ideal for demonstrating UI interactions, complex workflows, or system architecture.

  4. Time Constraints:

    • Keep videos concise, aiming for 2-10 minutes in length.
    • For extensive topics, create a series of shorter, focused videos.

Best Practices for Video Creation ​

  1. Discoverability:
    • Include clear, descriptive titles for each video.
    • Provide a brief summary of the video's content in the description.
    • Use timestamps for key sections to enhance navigation.
  2. Integration:
    • Link videos within relevant sections of text documentation.
    • Create a centralized index of all video content for easy reference.

How to record a video ​

  • Loom (we have a license which will allow us to record >5 min videos and also allow us to download the videos.)
  • Zoom (record a meeting)
  • QuickTime (for macOS users)

Markdown Formatting ​

Docs are written in Markdown, namely using GitHub-flavored Markdown (GFM) that is a superset of CommonMark (another Markdown specification). It also uses some VitePress-specific and other extensions.

Ideally, a raw MD text should be readable in editors and rendered in GitHub, VitePress, and other Markdown renderers.

VitePress ​

We use VitePress (default theme) to build and render documentation site from Markdown files.

There are some custom containers you can use to improve readability. Info box example (works on VitePress only):

Look here!

This is an info box.

Syntax for this container:

md
::: info
This is an info box.
:::

Supported containers: info, tip, warning, danger, details.

Check out the documentation for the full list of Markdown extensions.

An alternative, GitHub-flavored Markdown (GFM) alerts syntax is also supported by VitePress:

NOTE

An option to highlight a "Note" and "Warning" using blockquote

But it's not possible to customize headings of such GFM alerts (discussion full of requests for this). Giving this, VitePress syntax (::: info) is preferred for docs from the /docs directory.

Running Vitepress locally ​

Please check VitePress config doc.

HTML ​

As any Markdown, it also supports HTML tags. For example, you can use <details> and <summary> tags to create collapsible sections.

Diagrams ​

See diagrams.

Images ​

The docs contain images hosted on GitHub. However, since GitHub introduced signed URLs, we can no longer embed such images directly in the documentation. Please include images in the images directory, located at the same level as the documentation you are adding or updating.

Video Documentation ​

▶️ The Way We Write Documentation With Kazik and Jens
Recorded on September 18, 2024 · 8 minutes
Module documentation ratings explained; Examples of IxDF Gold Standard documentation we strive to achieve; Mermaid.js demo; PR template demonstration

FAQ ​

  • Q: What’s the "status" of docs right now?
  • A: There is always something to improve, and that’s OK! We in late 2024 we defined a Golden Standard for documentation and we are working on improving the quality of our docs to meet this standard.