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
Left hand menu 	Menu on the left side of the screen containing links to "Details", "Accounting" etc. in patron accounts or to "MARC View", "Holds" etc. for bibliographic records	
* Preferred form: "Left hand menu" and "Links in the left hand menu"
* Non-preferred form: "Tabs on the left side"
Tabs in the page 	In a single page, tabs that have a functionality and show different views without linking to a different page. Like "Holdings" under the bibliographic record. 	
* Preferred form: "Tabs"
* Non-preferred form: "Holdings section" or "Area below"
===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 ===
When you are describing a function that can only be used if a patron permission is set, use a note to indicate that this specific patron permission must be set (or the superlibrarian permission) and link to it as well as to the superlibrarian permission.
For an example note, check the note on the Patrons page about adding a patron:
Adding a patron
When documenting the permissions themselves, different headings are used for "top-level" or "parent" permissions like "circulate" and their "child" permissions like "circulate_remaining_permissions".
Always give the permission a label. This will allow other manual pages to link to the specific permission needed.
See ReStructuredText - Tips and Tricks#Permissions Format for more information.
For some examples, see the Patrons section on permissions:
Patron permissions
===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
Category:Documentation