Documentation - Content Development Guide

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

Propose to base on New Zealand Government Style Guide as it is licensed as CC BY 4.0 International (which can be incorporated into GNU GPL version 3.0 or later licensed material).

1. How we write

• Voice and tone
• Use plain language
• Language - US English (Simplified)
• References - for items not covered, authoritative style guide (The IBM DITA Style Guide: Conventions for writers and editors)

2. Grammar (include a description, guidelines, and examples)

• Abbreviations
• Capitalization (including headings)
• Commas
• Contractions
• Location referencing (above, below)
• Titles (for documents or publications)

3. Punctuation (include a description, guidelines, and examples)

• Apostrophes
• Bold
• Em dash
• En dash
• File types and extensions
• Hyphens
• Keyboard shortcuts
• Periods (full stops)
• Plurals
• Italics
• Parenthesis (brackets)
• Quotation marks

4. Links

• Placement of link text
• Writing links
• Opening links in a new tab or window
• Using anchor links
• Linking to documents

5. Lists

• Bulleted lists (unordered lists)
• Numbered lists (ordered lists)
• Task lists (for task topics)
• Tips for more complex lists

6. Numbers, dates and times

• Numbers
• Dates and times

7. Symbols and currency

• Symbols
• Currency

8. 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)
• Interface elements
• Selectable areas
• Word usage - A-Z

(Either have an A-Z index of terms or organise by category, maybe both?)

Information model

TO DO

Content strategy

TO DO

Supporting processes

• Using Git for version control:
  • Using git cherry-pick to make changes to previous versions of the manual