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:
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.
|
| 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:
|
| Course catalogue | Packages of training modules organised into standard courses. |
| Training modules |
Training modules that cover each item in the learning plan. Includes:
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:
|
| 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.
|
| 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. |