If you'd like to contribute to this user guide, all you have to do is sign up to
GitHub, and make a pull request against the BookBrainz User Guide
repository. The user guide
is written in Markdown format, which is easy for people with no coding
experience to edit. Please follow the documentation guidelines on this page when
writing documentation.

Documentation Guidelines

Purpose

This guideline is designed to help people write pages of documentation that fit
in well with the rest of the BookBrainz user guide. A section on general
documentation guidelines is followed by advice for writing specific types of
documents. It is hoped that through this guideline, the BookBrainz
documentation can remain more consistent and easier to use.

General Guidelines

This section describes general guidelines you should follow when writing any
type of documentation.

• Titles - Try not to use more than the three levels of headings. Text with
  lots of levels can be hard to understand, and generally covers too much
  material. Headings should be capitalized just like entity names in BookBrainz -
  generally, first letters of words should be capitalized, apart from for
  specific words.
• Clarity - Documentation should be very easy to understand, so sections
  should be as simple as possible. If a section becomes too long, move it to a
  new page and leave a short summary in its place. If you find yourself using
  long, complicated words, go back over what you've written and see if it can be
  rewritten to use short, simple words. Try to use a personal, conversational
  tone of writing.
• Entities - The first time a type of entity is mentioned in a document,
  the word should be linked to the entity documentation page.
• See Also - You should write a "See Also" section for a page if there are
  any other relevant documentation pages, to help readers get a better general
  understanding of topics, and to encourage further reading.
• Reference Links - Always use Markdown's reference links
  instead of inline links. This ensures that links are collected together at the
  bottom of the document, helping future editors maintain the user guide in cases
  where linked documents move.

Style Guidelines

The following guidelines should be followed when writing style guidelines.

• Inverted Pyramid - Use an inverted pyramid style of writing. This
  means introduce the topic first, giving a broad outline, then in subsequent
  paragraphs go into further detail. This helps people who just skim read to get
  a general idea of the content of the page, and more generally, helps people to
  know whether they should read further.
• Purpose - For each style guideline, create a section at the beginning of
  the page detailing what problem it’s intended to solve, and how it is intended
  to solve it.
• Template - When you create a new style guideline, copy the source of the
  style guideline template. This will provide you with the basic structure that
  style guidelines are expected to follow. Fill out each section of the template
  with your content.
• Examples - Aim to use at least one example for each key point you make in
  a guideline. Examples help people understand content, by allowing them to
  visualize what's going on, and work out how they can apply guidelines to their
  editing.