Documentation - Content Development Guide

From Koha Wiki
Jump to navigation Jump to search

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

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).

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)

Grammar

(include a description, guidelines, and examples)

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

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

Links

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

Lists

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

Numbers, dates and times

  • Numbers
  • Dates and times

Symbols and currency

  • Symbols
  • Currency

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

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.

Indications of versioning goes here?

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.

Content strategy

TO DO

Supporting processes

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