Documentation - Plan

Documentation plan for Koha 22.05 onwards. Continue to maintain and improve existing documentation until prototype is available and decisions are made.

Printable version (as at 3 December 2021): PDF ODT

Note: Updates, corrections, and discussion are welcome - on the Docs mailing list, IRC or the Talk page.

Change log

Date	Change
17 October 2019	Initial public release
3 December 2021	Minor updates, roadmap updated, made printable version available on Wiki

Executive summary

Documentation is an important part of making it as easy as possible for organisations to adopt and use Koha.

This document sets out a plan to create and maintain a core set of customisable documentation for the Koha community, including:

• Guides and manuals.
• Training material.
• Promotional material.

Documentation will be topic-based, modular and reusable.

Mission and goal

Mission

Make it as easy as possible for organisations to adopt and use Koha.

Goal

Create and maintain a core set of customisable documentation for the Koha community, including:

• Guides and manuals
• Training material
• Promotional material.

Benefits

• Support Koha's reputation as one of the best free and open source library management system.
• Make it easy for organisations to consider and adopt Koha.
• Enable Koha community members to quickly customise a core set of material for their needs.

Measures of success

• Updated documentation is available at the same time as major releases.
• Participation in developing and providing feedback on documentation steadily increases.
• Adoption rate by Koha support organisations.
• Positive improvement in appropriate metrics – including usage, feedback, and contributions.

Approach

Process

The general approach for developing documentation is:

• Prepare information product plan or brief: covers purpose, audience, messages, outline of content
• Write draft content
• Refine content
• Add graphics and images
• Review (technical, grammar and language, code)
• Finalise
• Translate
• Maintain.

Appropriate methodologies will be used for developing documentation.

Maintenance

• Anyone can create a documentation 'bug'.
• These will be triaged and added to the documentation task list.
• Documentation is reviewed and updated with each release.

Standards

Standards will be created as part of developing the initial set of documentation and included in a content development guide. This will include processes, tools, formats, and a style guide.

Source format

The proposed source format for all content is LightWeight DITA (LwDITA) using Markdown, rather than XML or HTML. This is a easier to use version of DITA XML, an OASIS standard and approach used in technical communication to create modular, reusable documentation.

Instead of creating narrative style, chapter-based documentation, you create a series of smaller topics which are mixed and matched using a ‘map’ (like a table of contents) to create different information products. If a topic is used in multiple places, then it only needs to be updated in one place, and then it is updated wherever it is used.

Topics are self contained and cover one subject. Standard topic types include:

• A task topic (for step-by-step instructions).
• A reference topic (for information that is used for reference or lookup).
• A concept topic (explaining how something works).
• A troubleshooting topic (for fixing problems).

Output formats

All documentation will be available in multiple formats, such as ODF, DOC, PDF, ePub, HTML. The primary formats are HTML and PDF. Training material can be used in learning management systems (such as Moodle).

Review

The community will be asked to review and provide feedback on the documentation.

Copyright

Documentation, unless otherwise stated, will be licensed under the GNU GPL v3 or later. Special care is required to ensure that material copied or adapted from other documents and sources can be used.

Audiences

The audiences for Koha documentation include:

Audience/role	Description	Requirements
Decision makers	People responsible for making a decision about what systems to use, and who authorise funding.	What problems does Koha solve for me? What are the benefits of using Koha? Why should I change from our current systems? What support, training and documentation is available? What future changes are planned for the future of the product?
Library managers	People responsible for managing a library.	What problems does Koha solve for me? What are the benefits of using Koha? Why should I change from our current systems? How do we manage the change to Koha? What support, training and documentation is available? What future changes are planned for the future of the product?
Library staff	Staff who work day-to-day with the library management system.	How does it work? How do the current things I do work in Koha? What does it improve for my 'customers'? How do I use Koha?
Library members	People who are members of a library and use its services.	How do I use the library website and online services?
Library system administrators	Those responsible for making sure that Koha is configured and maintained for an organisation.	How do you install and manage a Koha installation? How do I configure and customise Koha for our library requirements? What support material is available? For example, tutorials, how tos, etc.
Implementers	Those responsible for proposing and/or implementing Koha.	How do you implement Koha? How can I migrate the data from my existing system?
Potential Koha community members	Those that are considering Koha or looking for a library management system.	What Koha is and why they should consider using it (advantages and disadvantages, Koha's focus and philosophy)?
Koha contributors	People who contribute to the development of Koha.	Help contributors get up to grips with contributing to Koha – whatever aspect – including developers as well as other roles within the community.
Koha support companies and individuals	Individuals and companies that provide Koha support and services.	How to use, customise and contribute to the documentation.

The audiences work in all types of libraries:

• Public libraries
• University and higher education libraries
• School libraries
• Corporate libraries
• Non-profit sector
• Special libraries.

The audiences are mainly professional library staff (with library-related qualifications), but may also include non-qualified library staff (for example, volunteers that look after a non-profit library).

Products – guides and manuals

These guides and manuals will be developed:

Document	Description
Library member guide	Guide covering the basic and advanced features of Koha.
Library staff guides	Information at the appropriate level (in line with the learning plan) for library staff covering each of the main modules and common day-to-day library activities. Levels are: Fundamentals Intermediate Advanced Includes complete guides, quick reference cards and videos as appropriate.
Administration guide	Guide for system administrators on how to install, configure, customise, and maintain a Koha system.
Getting started	A basic walk through of setting up Koha for the first time.
Developers guide	Guide for Koha developers on how to program and develop for Koha.
Implementation guide	Guide to implementing Koha.
Reference manual	All guides and manual content combined into a complete reference guide to Koha.
API reference	Reference to any API methods available to external applications and services.
Community member guide	Set of information for new community members, including a contributor guide.
What's new	Detailed release notes covering what's new for each major release.
Help/support centre	Detailed help about Koha – all information in one place (guides, tips and tricks, release information, frequently asked questions).
Koha starter kit	Complete kit to get you started using Koha – from installing, setting up for your library and importing existing data.

Products – promotional materials

Core products

These core promotional materials will be developed:

Document	Description
Product overview	Printable brochure. Two to four page summary.
Product brochure	Describes what Koha is, the benefits, summary of main features, overview of the community, free software and why organisations should consider using Koha. Five to ten pages.
Product feature summary	A comprehensive feature summary of Koha – more in-depth than the Koha product brochure. 20 – 30 pages with screen shots and links to further information, for example: videos, manual, guides, and so on. Supported by the slide decks.
Slide decks	A comprehensive set of slides that can be remixed depending on audience – from and overview level to in-depth. Overview Detailed summary In-depth Examples.
Website material	For Koha 'product page': use information from the above materials to present a good overview of Koha, similar to product pages for other products.
Fact sheets	Set of fact sheets on important topics, for example: technical specifications, release cycle, how Koha is developed, the Koha community. One to two pages.

Other products

Once the core set of materials is developed additional promotional material could include:

Document	Description
Brochures: short brochures covering specific topics and audiences	Short brochures (two to three pages) and handouts, for example: Why consider Koha for your next ILS? Koha for academic libraries.
Fact sheets	Additional fact sheets that cover specific features and topics.
Technical briefs	Focus on specific technical specifications and features.
Postcards	Postcards with great graphics and messages on the front. With library themes, for example catalogue card, openness/flexibility. Maybe some great images from publicdomainreview.org.
Merchandise	Swag for use by community members and at conferences, for example t-shirts, badges, clothing, caps, bags, stickers.
Koha 'on a stick'	Live CD or USB stick, virtual machine images.
Banners	Free standing upright banners or wide horizontal banners.
Scorecard	One page summary of features and benefits with tick sheet. Summary of features for comparison to other systems.
Meeting/conference organisation pack	Meeting or conference pack to help community and support companies prepare successful stands at conferences, trade shows and meetings.
Tour	Website and slides with screen shots of main features and benefits. Video material.
Table cloth	Branded table cloth for conference and exhibit halls.
Supporters pack	Button, t-shirt, key guides, and so on.
Branding guide	Like Mozilla.
Posters	Posters that can be used to promote Koha.
New features summary	Guide to new features for a release (major releases, with updates to reflect minor release improvements).

Approach

Focus on benefits, not features – what problems does Koha solve?

Libraries with an existing library management system

Organisations with an existing library management system don't change or migrate to new systems often. They are often seen as expensive to run, inflexible, and migration is disruptive. It is not something undertaken lightly.

Strategic approaches to take:

• Provide a comprehensive overview of what Koha provides, with the ability to delve into the details.
• Raise awareness as a potential solution in the future for organisations that are not looking for a system right now:
  • overview
  • case studies and good news stories
  • regular news and information about Koha provided on appropriate forums such as library associations, library-related publications and mailing lists.

Libraries that don't have a library management system

For organisations that don't have a commercial library management system, such as a custom database or manual systems. These organisations may have limited budgets or expertise with a fully fledged library management system, or cannot afford one.

Strategic approaches to take:

• Emphasise benefits, features, flexibility, openness, cost effectiveness, and the Koha community.
• Make it as easy as possible to install and manage Koha:
  • Documentation, training and hosting services available
  • Demo so they can try it out
  • LiveCD, USB or virtual images for testing.

Products – training

These training materials will be developed:

Document	Description
Learning plan	Sets out the key skills and knowledge required to use, administer, develop and implement Koha. Levels: Fundamentals (green) Intermediate (blue) Advanced (grey)
Course catalogue	Packages of training modules organised into standard courses.
Training modules	Training modules that cover each item in the learning plan. Includes: Participants guide: interactive material (such as videos to demonstrate key features) and exercises Trainers guide: guide for trainers for instructor-led training (on site or via the internet) - includes slide decks, answers Material will support instructor-led, self-paced and web-based training.</li></ul><p>The training will be based on an example library and work through the set-up and use of the system for the different audiences (library members, administrator, manager, and so on.). The training will also be in a format suitable for import into learning management systems such as Moodle.
Tutorials	Short tutorials to supplement core training material.
Quick reference cards	Cover the essential information in a one or two page summary.

Roadmap

The first step is to create a prototype using LightWeight DITA for a single guide, such as the installation guide, to test how this works.

If it works as expected then next steps could include:

Task	Description/key outcomes	Key activities
1	Develop documentation guidelines and processes - to become part of the content development guide Note: ongoing through first iterations	Write content development guide, including: Development process Style guide Tools Revision control Translation process Licence
2	Prototype to demonstrate what is proposed	Create a prototype with sample content (such as the installation guide or system preferences) so that the Documentation Team and Koha Community can get some idea of how things will look and work, and determine whether making the change is worth the effort.
3	Training for Documentation Team	Develop and deliver training to help everyone get used to topic-based authoring approach using LwDITA and Markdown.
4	Existing material – convert to LwDITA (using Markdown)	Convert existing material to LwDITA (using Markdown) from manual, source code, wiki, website, and so on. Identify topics that required development and create maps that align with products. What's new Installation guide Community member guide Learning plan Product summary Getting started guide
5	Progressively develop information products	Initial products: Then refine list of other products and prioritise.
6	Product maintenance	Update each product progressively with every release.