From Koha Test Wiki MediaWiki Postgres

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

Contents 1 => New writers, start here! <= 1.1 How do Bugzilla, Taiga and Gitlab work together? 2 To do list 3 Editing the manual - using the GitLab web interface 3.1 Workflow 3.1.1 Mirroring repositories 3.2 Adding screenshots 4 Editing the manual - using a local repository and editor 4.1 Setup 4.2 Workflow 5 General hints and tips 5.1 Formatting with reStructuredText 5.2 Capitalization and spelling 5.3 Formatting 6 Translating the manual 7 Older manuals 8 See also

=> New writers, start here! <=

Hi! Welcome to the Documentation Team! Here's some information to get you started.

1. First, you need a GitLab account. Go to the website and register.
2. Then, you need to go to the Koha manual project and click "Fork". This will make a copy of the project in your account.
3. Next, you can read how to edit the Koha Manual here #Editing the manual - using the GitLab web interface

Read up on ReStructuredText which is the format used to write the manual.

Finally, we encourage you to create an account on Taiga.io and join the koha documentation team there. This is where all the tasks for new version of the manual are written.

This is also a great starting point if you prefer video: Virtual Hackfest 2020 Documentation.

Another video, a bit more complex, done during Kohacon20 hackfest : Editing the manual LIVE!

How do Bugzilla, Taiga and Gitlab work together?

This is an explanation of the current workflow, which is under discussion. Any ideas on how to streamline it are welcome.

Note: see the IRC logs for the original discussion

Bugzilla

• Developers work on new features, enhancements and bugs on Bugzilla (we call them all "bugs" even if they are new features or enhancements)
• 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.
• There are also Documentation "bugs" on bugzilla
  • If people notice typos, missing sections or section that could be better, they can file a bug and choose the Documentation component

Taiga

• Taiga is where all the "new" things to be added to the manual are housed (not corrections)
• The elements in Taiga are taken from the release notes of each version (meaning bugzilla bugs that are pushed to the development version of Koha)
• The reason it is currently separate from bugzilla is that the documentation team is not part of the development workflow on bugzilla - The developers have a defined workflow that all bugs must go through (sign off, QA, push to master, push to stable, push to oldstable, etc.) and there is no step for documentation so the documentation team created their own thing

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

In short

• Check Bugzilla or Taiga to find something to write about
• Go to GitLab to write and add your bit to the manual

To do list

Please file any issues with the manual as a bug report on Bugzilla using the Documentation component.

There is also a saved search for Bugzilla, that looks for bugs with the keyword Manual or the component Documentation

Documentation related bug reports

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.

If you want to discuss things about documentation or send us your documentation to include in the manual, you can sign up on the koha-docs mailing list or join us for the next Documentation IRC meeting.

The Documentation Team uses Taiga.io to manage documentation tasks.

Editing the manual - using the GitLab web interface

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!

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.
   • The first time you connect to Gitlab, 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.
   • In your project, go to Settings > Repository > Mirroring repositories and set up your mirror as described below
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 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.
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.
   • 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!

Mirroring repositories

• Keep your fork of the Koha manual up-to-date using mirroring (otherwise you will have to fork the repository each time you make a change): Settings > Repository > Mirroring repositories, where:
  • Git repository URL = https://gitlab.com/koha-community/koha-manual.git
  • Mirror direction = pull
  • Authentication method = Password
  • Password (create your password)
  • Overwrite diverged branches = yes (check)
  • Trigger pipelines for mirror updates = no (leave unchecked)
  • Only mirror protected branches = yes (check)

• • Click "Mirror repository"

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.
   • Go to the images.rst file, found under koha-manual/source.
   • Click on Edit.
   • Go to the bottom of the file and add a line referencing your image. The syntax is the following:

     .. |image1355| image:: images/tools/importpatrons/patronattributes.png

     where

     • .. = this means it's a comment line, it will not appear if you look at the rendered page
     • |image1234| = this is the alias of the image to be used in the manual. Use the next number in the file (for example, if the last number in the file is 1234, use |image1235|).
     • 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
   • 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: |image2201|.

     

   • 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_master" to track that second remote

   git checkout -b community_master community/master

Workflow

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

   git checkout community_master

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

   git pull

   • Merge your local "master" with your local "community_community" branch

   git checkout master

   git merge community_master

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

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)

Formatting

See the Documentation_style_guide

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