Koha Test Wiki MW Canasta on Koha Portainer

Test major Koha Wiki changes or bug fixes here without fear of breaking the production wiki.

For the current Koha Wiki, visit https://wiki.koha-community.org .

Documentation - Plan

From Koha Test Wiki MW Canasta on Koha Portainer
Jump to navigation Jump to search

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.