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

Koha interface element conventions
Interface element	Description	Example
Buttons names	Use single quotes and capitalization for button names	Preferred form: Click the 'Submit' button. Non-preferred form: Click the submit button.
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.
Try to stay at 100% zoom in the browser, only change the zoom if necessary to e.g. show the full table if it would otherwise be cut off
For functions that are grouped in a menu, e.g. Patron account tabs on the left hand side for Circulation, Accounting, ... etc.: Only include the "left hand menu" in the first screenshot and not for the individual function
Recommended tools: Greenshot, Flameshot (for Linux and Windows)
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