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.
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 an Edition alias 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.
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 visualise what's going on, and work out how they can apply guidelines to their editing.