Editing the Koha Manual

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

Interested in Koha Documentation in general? Contribute and join the team!

Useful links

• GitLab - where the source files for the manual live. GitLab is also used to submit updates; you will need an account there to edit the manual.
• Bugzilla - to find things to write about. You will also need an account there, to mark bugs as documented.
  • Needs documenting status - all the bugs waiting to be documented
  • Documentation component - bugs about the Manual plus bugs that were waiting to be documented before the Needs documenting status was created.
  • Manual keyword - another way bugs used to be marked for documentation before the Needs documenting status was created.
• Content development guide - for indications of how to write for the Manual and what goes where.
• ReStructuredText tips and tricks - to understand and learn the formatting used in the Manual source files.
• Koha Community Chat on Mattermost - to find Documentation team members and get help.

Bugzilla and GitLab workflow

In short

• Check Bugzilla to find something to write about.
• Go to GitLab to write and add your bit to the manual.
• Go back to Bugzilla to update the bug.

Let's clarify what each of the platforms do.

Bugzilla

• Developers work on new features, enhancements and bugs on Bugzilla.
  • We call them all "bugs" even if they are new features, enhancements - or requests for documentation!

• This is the source of every bit of code in Koha.

• Bug reports are a great place to understand what features do. Developers will write test plans or descriptions of what the feature does in bug reports.

Gitlab

• GitLab is where the manual lives, it is where all the versions of the manual are housed and where all the changes are made
• That's where you need to go to do any contributions to the manual.

Workflow

This is an explanation of the current workflow. Any ideas on how to improve it are welcome.

1. Find something to document.
   • The Koha dashboard shows the 10 oldest bugs with the status "Needs documenting". It links into Bugzilla.
   • On Bugzilla, search for bugs with the status "Needs documenting".
   • On Bugzilla, you can also check a saved search (when logged in) named Documentation "To-do" list. It includes bugs marked with:
     • Documentation component: includes typos, missing sections or section that could be improved;
     • "Manual" keyword: older bugs that have been marked as needing documentation;
     • "Needs documenting" status: bugs that have reached the documention stage after development is completed (as of June 2022, the status 'Needs documenting' has been added to the Bugzilla workflow after 'Pushed to xx').
   • Documentation bugs for beginners: for tiny fixes like links formatting and typos, search Bugzilla for Component=Documentation and Keyword=Academy.
2. Choose a bug you would like to document. Prepare your text and screenshots. Check where they will fit in the current manual.
   • If you start working on documenting a bug, you can enter your name in "Documentation contact" on the bug page in Bugzilla.
3. Go to GitLab and submit your changes as explained in the relevant Editing the manual section below.
4. Once a merge request has been sent through Gitlab, go back to the bug page on Bugzilla and enter the link to the merge request in "Documentation submission".
5. Once your GitLab request has been merged, go back to the bug page on Bugzilla and:
   • Change the status from "Needs documenting" to "Resolved - Fixed". Not only will this show the bug does not need documenting, it will also add your name to the Koha dashboard's contribution lists.
   • It's nice if you can add a comment too, to say this feature is now on the manual.

Special cases

• Your bug doesn't have the "Needs documenting" status.

Your bug has the Documentation component or the "Manual" keyword; its status may be "new" or "resolved" - or even "closed". In this case, change its status to "Needs documenting" - ideally when you start working on it and add your name in "Documentation contact" (stage 2 of the workflow).

• Your bug has the "Needs documenting" status but doesn't need documenting.

The "Needs documenting" status is now part of the Bugzilla workflow. Often developers will leave it to the Documentation team to decide whether a change to the Koha manual is required (additions or updates to the text and / or screenshots). Once you have ascertained that no changes are required, add a comment to the bug to explain and change its status to "Resolved - Fixed".

Editing the manual - using the GitLab web interface

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

Workflow

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. SSH message: Once logged in, this message may appear and it can be closed (i.e., ignored), "You can't push or pull repositories using SSH until you add an SSH key to your profile."
3. Create a "fork" (copy) of the manual repository:
   • Go to https://gitlab.com/koha-community/koha-manual and click "Fork".
   • This will make a copy of the manual in your account - you will always work in your own copy and then make "merge requests".
   • The Documentation manager will then check your work to make sure there are no errors and then merge your work into the real manual. This helps avoid errors.
4. Navigate manual files: Once you are logged in, you can navigate to the Koha manual on GitLab and get yourself a bit familiar with its file structure.
   • You will find all the text in source, for example administration.rst will have all the information about the administration module except for the system preferences that live in systempreferences.rst.
   • 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.
5. Create a branch for your proposed changes: We recommend making changes on a new "branch". This keeps the main branch of the manual (called main) clean.
   • Go to [Your fork of the manual] > main branch > + > New branch.
   • Give the branch a name, for example the bug number you are working on and a short title: for example, bz32011-2fa
6. 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. You can use the Gitlab Web IDE (similar to VSCode) using Edit > Open in Web IDE. If you are only changing one file, it is probably easier to use Edit > Edit Single File. In this case you don't have a web IDE (so you don't see any formatting, highlighting, etc.) but you can make the changes directly in the text of the file. This is faster if you are only making small changes to a single file.
   • Make your changes in the editor. The formatting is done using reStructuredText.
7. Save (or "commit") 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.
   • In the IDE, click the "Source Control" button (it looks like a connector or a wiggly Y with circles at each end; it should also have a badge with a number on it)
     

     Side panel of the GitLab IDE panel, with the Source Control button highlighted
   • Enter a short description in the commit message input field. 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.
     • Recommended practice for the subject line is Bug number: Short title (for example, Bug 32011: Document 2FA changes)
   • Click "Commit and push to 'branch'"
   • Next time: Commit changes to submit the changes to your fork of the repository.
   • After committing your changes, go back to GitLab (get out of the IDE). It 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.
8. Delete the branch you created once your changes are merged: Once your changes are merged into the manual, you can delete the branch you created:
   • From the menu at the left select Code > Branches
   • For the branch you created, select the three vertical dots on the right-hand side and select Delete branch
   • Read the warning message and confirm that you want to delete the branch: Yes, delete the branch
9. Update your fork: To make sure you are making changes to the latest version of the manual you will need to update your fork:
   • Go to the repository home page for your fork of the manual
   • If your fork is not up to date, a message is displayed saying:

     Forked from koha-community / koha-manual           Update fork
     XXX commits behind the upstream repository.

   • Click Update fork

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

Adding screenshots

This requires a little bit more work as you need to edit multiple files, but is not too hard to do:

1. Upload images: First, you need to upload your screenshots.
   • All images are stored in the directory source/images
   • In your repository, navigate to the directory where you want to add your images. For example, koha-manual/source/images/circ
   • At the end of the path shown on top is a plus ("+") icon. Click on it and select Upload file.

     

   • You can now upload the image(s), either using drag & drop or the click to upload link to browse your directories and select the file(s) you want to upload.

     

   • Finish with changing the commit message to some description, for example: Adding screenshots for feature xxx.
2. Create aliases for your screenshots: By using aliases we can change a file without having to change the documentation. Note: the documentation team used to number images in sequence. We are now moving away from this and using filenames as aliases for each image. You may still notice old aliases in the format |image1234| in the chapters and the image file.
   • Go to the images.rst file, found under koha-manual/source.
   • Click on Edit.
   • Find the relevant section to add your image, e.g. CIRCULATION. Order images in alphabetical order by filename/alias in each section or sub-section to make it easy to find them
   • Add lines referencing your image. The syntax is the following - shown here with an example for an iage showing the checkout settings:

     .. |checkoutsettings| image:: images/circ/checkoutsettings.png

     [indent] :alt: Checkout box with checkout settings section opened

     Where:

     • .. = this means it's a comment line, it will not appear if you look at the rendered page
     • |checkoutsettings| = this is the alias of the image to be used in the manual.
     • image:: = this is the syntax that calls the file to appear as an image (not a link or a string of text)
     • images/xxx/xxx.png = this is the path to the image and its name
   • If you are replacing an existing screenshot that has an alias in the |image1234| format, create a new alias for it and delete the line for the old one in the images.rst file.
   • Enter your commit message and submit the changes.
3. Add screenshots to the manual: Now that everything is in place, we can add the images to the manual.
   • Adding the screenshot now is quite simple. Just write the alias you created on a new line. For example: |checkoutsettings|.

     

   • Enter your commit message and submit your changes.

Editing the manual - using a local repository and editor

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. Note: the minimal required version of Sphinx is 1.4 at the moment. If your distro doesn't have that, consider installing python-sphinx with pip.

Setup

1. Fork the project in GitLab: Start by going to GitLab and forking the project. This will create your own personal repository with a copy of the manual.
   • Go to GitLab and sign in or create an account
   • Next, go to https://gitlab.com/koha-community/koha-manual and click on the "Fork" button

   

2. Set up your SSH credentials
3. Set up koha-manual repository: Clone the koha-manual git repository from GitLab
   • Go to your own GitLab repository, click on "clone" and copy your SSH URI

   

   • Next, open up a terminal window and clone your GitLab repository

   git clone <your SSH URI> koha-manual

   • Go into your newly created repository

   cd koha-manual

   • Next, add a second remote called "community" to pull from and fetch

   git remote add community git@gitlab.com:koha-community/koha-manual.git

   git fetch community

4. Create a new branch called "community_main" to track that second remote

   git checkout -b community_main community/main

Workflow

1. Make sure everything is up-to-date: pull from community/main
   • Go to your local koha-manual folder and checkout on the community_main branch

   git checkout community_main

   • Pull the latest version of the manual from the community repository

   git pull

   • Merge the community_main with your local "main" branch:

   git checkout main

   git merge community_main

   • Update your remote main (to keep it up to date)

   git push

2. Create a new branch: before you start changing files, always create a new branch for your changes.

   So for example, if you're going to work on the RenewalLog system preference, create a branch using the following command

   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
   • Navigate to the file you need to change, all files are in the "source" directory

   cd source

   • Open the file in your text editor (for the example, we'll use vi) and edit the file

   vi systempreferences.rst

   • Basic vi commands
     • i - insert (edit)
     • Esc - get out of editing/inserting mode
     • :w - write (save)
     • :q - quit (close the file)
     • / - string search (case sensitive) (for example: /RenewalLog)
4. Commit your changes: commit your changes to make sure nothing is lost
   • Start by adding the files that were changed to the staging area

   git add --all

   OR

   git add *.rst

   OR

   git add systempreferences.rst

   • Commit your changes

   commit -m "Adds description for RenewalLog syspref"

5. Push your branch to your GitLab koha-manual fork

   git push (this will create a branch of the same name in your GitLab repository)

6. Create merge request
   • Go to your GitLab account
   • Go to Repository > Branches

   

   • Find the branch you want to push and click on "Merge request"

   

   • Click on "Submit merge request" at the bottom of the page

Build the manual locally

Having a local copy of the manual means you can build the manual (create the HTML files from the .rst files) and see your changes immediately.

1. In a terminal window, go to your local koha-manual folder
2. Run the build command

   make html

   This command will create the html files in the build/html/ folder

   Note: This will create the html files from the branch you are currently on

   It may show errors. This is a list of some errors you may encounter

   • WARNING: duplicate label known issue caused by some section headings that are the same in different chapters
   • WARNING: undefined label the reference is not formatted correctly, or references a section that doesn't exist
   • ERROR: Undefined substitution referenced the reference to the image is not in the images.rst file
   • WARNING: image file not readable the image path in the images.rst file is doesn't correspond to anything in the images/ folder

   The errors will tell you in which file and on which line the error is so you can go and correct it. For example

   koha-manual/source/webservicespreferences.rst:195

   means the error is in the webservicespreferences.rst file, on line 195.

3. Go to the build/html/ folder and open the html file for the chapter you were working on

Rebuild (make html) every time you do a change to see the change reflected in the html file.

Check the spelling

Having a local copy of the manual means you can run the spell check after your changes to make sure you didn't inadvertently add any typos.

1. In a terminal window, go to your local koha-manual folder
2. Run the spell check command

   make spelling

   This will show all what the script considers spelling errors in the terminal, but the errors are also saved in the build/spelling/ folder

3. Go to the build/spelling/ folder and open the file for the chapter you were working on

   The error will say the file in which the spelling is incorrect, the exact line, the current word between parentheses, suggested spellings between square brackets, and the sentence. For example:

   `acquisitions.rst:1471: (Cancelling) ["Canceling", "Cancel ling", "Cancel-ling", "Excelling", "Changeling", "Calling", "Angelica"] Cancelling orders`

   means the script found an error in acquisitions.rst, on line 1471. The incorrect word is "Cancelling", and it offers possible spelling options between the brackets. It is followed by the sentence in which this word was found "Cancelling orders".

4. If the error is valid
   1. In your text editor, open the file and correct the spelling
   2. Save
   3. Run the spell check again

      The error shouldn't come up again

   4. Commit the change
5. If the error is not valid, it is a real word correctly spelled
   1. In your text editor, open the source/koha_spelling_wordlist.txt file
   2. Add the word to the list
   3. Save
   4. Run the spell check again

      The error shouldn't come up again

   5. Commit the change
6. If the error is not valid, it is a part of a word or a abbreviation
   • Unfortunately, there is not much we can do for spell checking abbreviations, urls, etc. We don't add them to the word list because they are not real words. They will stay in the errors.

General hints and tips

Formatting with reStructuredText

Sphinx uses reStructuredText for formatting the text:

• http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
• http://docutils.sourceforge.net/docs/user/rst/quickref.html

Also, a bit more specific to our manual: ReStructuredText - Tips and Tricks

Capitalization and spelling

• The terminology used in the manual should match the interface of Koha. See: Terminology
• The first word of a sentence should be capitalized, the following words will be lower case, unless they are names. For example: Koha, Chris, November, Monday, etc. See: Coding_Guidelines#HTML4:_Upper_and_lower_cases_in_strings.
• Prefer gender neutral pronouns (they/them/their). See: Coding_Guidelines#Gender-Neutral_Pronouns
• Use American English spelling (color, authorized value)

Style guidelines, structure and formatting

See the Documentation - Content Development Guide

Reporting problems with the manual

If you wish to report typos, error or any other problem with the manual, please file a bug on Bugzilla with the Documentation component.

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

1. Go to Bugzilla
2. Log in or create an account
3. From the main page, click 'New'
4. Click 'Koha'
5. Click 'Show advanced fields". Fill out the following on the report form:
   • Component: choose Documentation
   • Version: leave it at 'main' unless you want to specify that it is a problem with a specific version. Note that we currently do not have the resources to correct older manuals
   • Status: select Needs documenting
   • Summary: Enter a brief description of the problem
   • Description: Enter a detailed description of the problem, include as many details as possible, with URLs to orient us
6. If needed, you can add screenshots as attachments by clicking 'Add an attachment'
7. Click 'Submit Bug'

Translating the manual

See Translating the Koha Manual

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

• Manuals on the koha-community.org website
• https://gitlab.com/koha-community/koha-manual
• Translating the Koha Manual
• Koha Manual - more technical information about how the manual is generated
• Git guide for documentation - Quick reference guide for those new to Git and who are not developers