Editing the Koha Manual

From Koha Wiki

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

The Koha Manual is managed by the Documentation team and everyone is invited to help out writing and updating it.

Contents

To do list

To make it really easy to comment and add your name to a to-do list item we have set up a pad:

https://annuel2.framapad.org/p/KohaManualTodo

Please feel free to add new to-do list items for missing chapters/information, things you didn't spot on the manual or suggestions of any kind.

Editing the manual

Starting with the manual for 17.05 we have switched from DocBook to Sphinx for creating our documentation. This makes it really easy to contribute.

Easy - Editing with gitlab

The easiest way to contribute to the manual is making your changes using the following workflow with gitlab. You don't have to download or install anything for this to work, it can all be done in the browser!

  1. Gitlab account: First of all, you have to create an account on gitlab. You can also sign in with an existing Google, Twitter, github or BitBucket account.
  2. Navigate manual files: Once you are logged in, you can navigate to the Koha manual on gitlab and get yourself a bit familiar with it's file structure.
    • You will find all the text in en/source, for example 02_administration.rst will have all the information about the administration module and system preference descriptions.
    • You can also use the option to 'Search this project' at the top of the page. For example, you could search for AcqCreateItem to find the spot where this system preference is described in the manual.
  3. Start editing: Once you have located the file you want to change, you can use the Edit button on top of viewed file to start the editing process.
    • Make your changes in the editor. The formatting is done using reStructuredText.
    • Add a short description in the commit message input field below the editor. The first line is going to be the subject line, all other lines below will also be shown when looking at your changes in detail.
  4. Save your changes: Saving your changes will create a merge request to be seen by the documentation team. You can see your open merge requests on your gitlab account.
    • First time: Fork will create a fork of the kohadocs repository in your gitlab account.
    • Next time: Commit changes to submit the changes to your fork of the repository.
    • After committing your changes, gitlab will automatically ask you to create a merge request. Here you can edit the description again, but don't change any of the other settings. Click Submit merge request and you are done.

Check out this video for a demonstration on how to edit using gitlab!

Advanced - Editing from local repository

It's recommendable to try the gitlab workflow first as it's easier and doesn't require any familiarity with git itself like this workflow:

  1. Set up kohadocs repository: First of all you need to clone the kohadocs git repository from gitlab and install Sphinx.
  2. Create a new branch: before you start changing files, always create a new branch for your changes. Example: git checkout -b RenewalLog
  3. Start editing: Edit the files with your preferred editor.
    • You can use git grep for searching in the files. Example: git grep RenewalLog
  4. Commit your changes
  5. Push to your gitlab kohadocs fork
    • Create a remote for your kohadocs fork in your local repository. When you have used the gitlab workflow before, it will already be there. Otherwise you can create it from the web interface manually. Example: git remote add <local name> <link to your gitlab repo>
    • Optional: Add an SSH key to your gitlab profile to not require to enter your gitlab credentials every time you push.
    • Push your new branch to gitlab. Example: git push <local name> <local branch>:<remote branch>
  6. Create merge request
    • It looks like there is no native way to create a gitlab merge request from command line. There are some tools out there, to do that, but none has been tested so far.
    • Create the merge request on gitlab using the following instructions.

General hints and tips

Formatting with reStructuredText

Sphinx uses reStructuredText for formatting the text:

Capitalization and spelling

Translating the manual

To be added...

Older manuals

The older manuals up to Koha 17.05 were generated using DocBook.

To edit the older manuals an XML/DocBook editor like oXygen is recommended. Every chapter and section must have an ID tag associated with it to enable permanent linking and searching.

Patches to the manual can still be emailed to the koha-docs mailing list, but as Koha moves on, it makes sense to favour updating the new Sphinx based manuals instead.

See also

Personal tools