Documentation - Plan

From Koha Wiki

Jump to: navigation, search
Home > Documentation
Koha > Community > Participation

Draft documentation plan - for future Koha releases. Continue to maintain and improve existing documentation in the meantime.

TO DO - Add printable version

Contents

Change log

Date Change
17 October 2019 Initial public release

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)
  • Translate
  • Maintain.

Appropriate methodologies will be used for developing documentation.

Maintenance

  • 'Doc bugs' can be created by anyone.
  • 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. This will include processes, tools, formats, and a style guide.

Source format

The proposed source format for all content is LightWeight DITA (LwDITA). This is a easier to user version of DITA XML which can used markdown, and is used to create modular, reusable documentation.

Instead of creating narrative style, chapter-based documentation, you create a series of smaller topics which can be mixed and matched using a map 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, cover one topic and are generally 'typed'. A topic will generally be a task topic (for step-by-step instructions), a reference topic (for information that is used for reference or lookup), and a concept topic (explaining how something works).

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 output as SCORM packages, which means it can be used in learning management systems (such as Moodle).

Review

Volunteers from 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:

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:

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:

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 e.g. videos, manual, guides etc. Supported by the slide decks.
Slide decks Comprehensive set of slides that can be remixed depending on audience – from overview 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 e.g. 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:

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, etc.
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 e.g. 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:

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.

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

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:

1

Develop documentation guidelines and processes.

Note: ongoing through first iterations

Write documentation guide, including:
2 Existing material – convert to DITA

Convert existing material to DITA from manual, source code, wiki, website, etc.

Identify topics that required development and create maps that align with products.

3 Progressively develop products

Initial products:

Then refine list of other products and prioritise.

4 Product maintenance Update each product progressively with every release.
Personal tools