Documentation - Content Development Guide
Warning: this page is under active development by the Documentation team (28 August 2024)
This is an outline and draft content for a content development guide for the Documentation Team. It will include:
- a style guide: guidelines for writing clear and concise content, including grammar and word lists
- an information model: structures and guidelines to help us write different types of content consistently
- a content strategy: a plan outlining how we develop content, including the types of information products we create, the tools we use, and the processes we follow
Style guide
Our base style guide
The documentation team uses the Google developer documentation style guide to help us write clear and consistent content.
Anything not covered by the Google style guide, and any differences from it, are covered or referenced in this page.
(Note: the Google developer documentation style guide uses the Creative Commons Attribution 4.0 License (CC BY 4.0).
How we write
- Use plain language
- Be clear and concise
- Use American English
General (to categorize)
- Use the 2nd person: you do this and that, instead of one does this or that
Active voice
Use the active voice instead of passive voice where possible.
Grammar
- Avoid abbreviations. If you use any, make sure they are explained.
- Do not capitalize headings. Use sentence case.
Links and references
When inserting links or references, have the text of the link be significant (also avoid links that say "click here"), for example:
- preferred form: :ref:`create a new authorized value category <add-new-authorized-value-category-label>`
- non-preferred form: :ref:`create <add-new-authorized-value-category-label>` a new authorized value category
Lists
- Use bulleted lists (unordered lists) to list items or points, where the order does not matter.
- Use numbered lists (ordered lists) when the order does matter.
Present tense TO DECIDE
Tense of verbs in sentences:
- Present: the number of holds is displayed; the button is on the right
- Future: the number of holds will be displayed; you will see the button on the right
Punctuation
- Always use punctuation in full sentences:
- End complete sentences with a period.
- Avoid bold: use a heading instead.
- Quotation marks: prefer single 'quotes', unless the content has an apostrophe.
Terms (including word lists of preferred and non-preferred terms and phrases)
- Koha-specific words and terms: see the Koha Community's terminology list.
- Actions (click vs click on vs select)
- Use the names of Koha interface elements and selectable areas
Titles and headings
- Use verbs and the present participle (adding an -ing), for example:
- preferred form: Adding an authorized value
- non-preferred form: Add an authorized value
- non-preferred form: Creation of an authorized value
- Always add a label, so that this section can be referred to elsewhere.
Structures and guidelines
Conventions for interface elements
| Interface element | Description | Example |
|---|---|---|
| Buttons names | Use single quotes and capitalization for button names |
|
| Module names TO DECIDE | Capitalized or not? In single/double quotes? In italics or bold? | |
| Paths TO DECIDE | Use > to indicate the path to follow to get to a page or to perform an action. | Koha administration > Basic parameters > Libraries |
Forms - describing the fields
When describing a form, use a bullet list and each bullet should start with the label of the field, for example
- preferred form: Name: this is the name of the field as you want it to appear.
- non-preferred form: Enter the name as you want it to appear.
- non-preferred form: Enter the 'Name' as you want it to appear.
Permissions
To document permissions:
- ... TO DO
Examples:
Screenshots
- Try to take general screenshots that can be reused in many places. For example, take a screenshot of all options in a menu rather than very specific screenshots of a single button or option.
- Classify the screenshots in the module where they were taken, rather than where the screenshot is used in the manual. For example, a screenshot of an OPAC message in the OPAC will be classified in the OPAC directory even if it is used in the patrons chapter to show how it looks to the patron when you add a message in their file.
- Alt text guidelines: TO DO
Source file formatting
- Cut lines at 80 characters if possible (not always possible, especially with tables)
- Do not cut ref links (it creates errors or warnings upon build)
- Follow bullet points with two spaces
System preferences
TO DO - Add a model and example for presenting system preference reference information.
Content strategy
TO DO
What goes where
Koha Manual vs. Koha Wiki
The Wiki is for...
- specific use cases and integrations
- sharing best practice, code, and examples, such as notices, macros, and the SQL library
The Manual is for...
- explaining how the software works
- how to use the settings for your library.
What's new page
From 2024, the Koha Manual features a What's new in Koha page. This page has a different role to the Koha release notes, as it shows what is newly documented with links to the relevant sections in the Koha Manual. We hope it will be useful to librarians, helping them to better understand which new features are available and how they work.
When documenting a new feature added in the latest Koha version, the documenter should consider whether to add a paragraph about it to the What's new page.
Add to the What's new page:
- new modules;
- new features;
- new system preferences;
- new options for command line tools.
Do not add to the page: something that just changed in that version.
We want the page to focus on the bigger things that didn't exist at all in Koha before.
Keep the title and description short and concise; the details will be in the link to the relevant section of the manual.
Formatting
See ReStructuredText - Tips and Tricks for how to format:
- Headings
- System preferences
- Ordered lists
- Images
- Links
- Notes
- Code blocks