GitHub Twitter Slack

# Writing Documentation

# General Guidelines

TODO: link a more extensive list of guidelines

  • Use simple language – documentation will be read by non-native speakers.
  • Stick to your wording – don't use a different word each time you refer to an action. As an example, don't confuse your reader by asking them to press the button, then click the button, and finally activate the button. Use either of those verbs and stick to it.
  • Address your reader directly – i.e. write you can do X instead of we can do X.
  • Add exhaustive links – if you refer to something that's documented, link to it. If it's not documented, create that documentation.

# Formatting Pages

  • Make use of the documented custom components in order to establish a consistent documentation.
  • Prefer custom components over tables. Tables don't render well on mobile phones.

# Custom Components

This documentation uses a few custom components which are meant to help writing better documentation.

  • The BlogIndex component is used to render previews and links for all blog posts.
  • The EventsIndex component is used to render upcoming and past events.
  • The CustomBadge should be used to highlight software versions capability (e.g. introduction or deprecation).
  • The custom block flag notation should be used to document command line flags, CLI commands, or other code related functionality.
  • The custom block attribute notation should be used to document YAML file structure.
  • The CommunityResources component lists resources like tutorials, videos, etc., from a JSON file.

# VuePress native functionality

  • There is no need to create table of content (TOC) manually. VuePress supports adding a TOC by simply adding a [[toc]] at the according position. The [[toc]] will render h2 and h3 headers. Note: if you want to accompany the TOC with a header Table of Contents, then you need to format this header with plain html <h2>Your Header</h2> on order to not have it listed in the TOC.

Some code snippets are included from KUDO that is included as a Git submodule (opens new window). When updating the docs for a new KUDO release, the submodule has to be updated as well. This is done by updating the KUDO version in scripts/bump-kudo.sh, running

./scripts/bump-kudo.sh

and committing this to kudo.dev.

Blog Posts →