Documentation - Content Development Guide
Warning: this page is under review by the Documentation team (22 January 2024)
This is an outline 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
The Koha manual style guide is based on the Google developer documentation style guide. We specifically recommend reading the sections on General principles, Language and grammar, Punctuation and Linking sections. (Note: the Google developer documentation style guide is published under the the Creative Commons Attribution 4.0 License.)
Some additional indications specific to the Koha manual are provided below.
How we write
- Use plain language
- Be clear and concise
- Language - US English
Grammar
- Avoid abbreviations. If you use any, make sure they are explained.
- Do not capitalize headings
Punctuation
- Always use punctuation in full sentences.
- Avoid bold: use a heading instead.
- Quotation marks: prefer single 'quotes'.
Lists
- Bulleted lists (unordered lists)
Terms (including word lists of preferred and non-preferred terms and phrases)
- Koha-specific terminology (see Terminology for initial list of terms)
- Actions (click vs click on vs select)
- Use the names of Koha interface elements and selectable areas
What goes where
Koha Manual vs. Koha Wiki
The Wiki is for...
- specific use cases and integrations;
- sharing best practice, code - e.g. notices, macros, 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