Documentation as a repository or branch

As we are moving forward with lh-toolkit development, I wanted to highlight some progress and get some feedback. The first thing I wanted to highlight was the issue board. I love the gitlab issue board - https://gitlab.com/librehealth/lh-toolkit/board

All our pipelines are passing using the Gitlab CI, we are testing, building and then deploying the branches. You can test them out here - https://toolkit.librehealth.io/master - i.e. toolkit.libhrealth.io/

The next thing we need to do is prepare a user manual and a developer manual. The wiki pages on gitlab are good, but they are not intuitive to be read in one single interface. There are too many pages to click and makes learning tedious. I want to use gitbook. See this example - https://pages.gitlab.io/gitbook . It allows writing the manual like a book, generates a ToC, responsive online book reading interface. What do you guys feel about gitbook? Should we also do a jekyll or hexo site too, for web presence purposes? We can then host it to https://toolkit.librehealth.io

Another question is whether documentation should be a repository like librehealth/lh-toolkit-docs or should it be a branch in the lh-toolkit repository? The web presence site is probably better in its own repo?

3 Likes

Toolkit, EHR, organizational, informational or otherwise, I think all documentation has the same needs, and can use the same throughput. Wikis stink. Delving data is hard enough, and most people simply use a search engine to get information out of them. Some folks can’t see why this is a problem. That is because they know what they are looking for, and have a term to describe it. The users go to documentation not knowing what they should be looking for. They need a lot of options in front of their face so they can delve into categories in a linear fashion. Search based documentation is inherently silly. If you know what you are looking for, you probably already know some of it…and you must.

It would be great to have a documentation workflow that:

Is a collaboration package that tracks changes much like a repo. Can set editing permissions (CANNOT be an open wiki!) and has an authorization system that accounts for standardizing terminology and formatting. Can output to a traditional manual, a tree menu driven system, and even out to a wiki or whatever if it must.

There are very few examples of good on-line documentation out there. The slick mobile stuff (think Microsoft Support) is mostly useless to a noob. Collections of data like this forum are also not so great. When you sign on here, you get a chronological list of activity, then you can sort it by tags etc… but it is very difficult to use anything here as a reference. This is easily exemplified by a recent question “Can you point me to the documentation?”. There was no documentation, but the layout did not make it readily apparent that it did not exist.

Recently, one of projects I have long used called “PDFSam” switched from a PHPBB forum for documentation to something new and slick. It is useless. Before, you could go there, look at it and say, “Uh, seems like I don’t have the current version, but I need support for it. Looks like there is a legacy support section with my version on it. OK, well, look there; It’s got the configuration help in there. I think that is what I need…” Successful use. You are now required to spend about 15 minutes and know exactly what you are looking for, then it has to refer you to the hidden link to original board, because all the people that used to post there have stopped, and there are no new posts or contributions.

Here is a terrible use of PHPBB as product documentation. https://community.apachefriends.org/f/ All the same, you can still go right where you need by glancing down the well ordered items on the screen.

Here is a pretty good one: http://www.phphelp.com/forum/index.php

Here is an excellent one, though it still only uses a couple of levels of sub categories: http://www.orbiter-forum.com/ If three or four levels were used, someone could navigate to exactly what they want without knowing what it is called, in very short order.

1 Like

Yes, we should share some of the best practices in documentation. Off course each project can choose their own, but discussing and finding a solution for documentation shouldn’t be very difficult.

I agree… forums are good for discussion, bad for someone new to find information. Even worse, if someone wants to read something in order. Sub-categorizing helps in finding the right place for information, but still doesn’t help people who are used to learning things in an order.

What do you all think about the gitbook example? It does track changes like code, allows for a tree-menu driven system and can allow people to submit changes when they find something problematic like merge requests to code.

1 Like

I am digging into gitbook at this very moment. Much of it looks promising, though none of it is anything that is new under the sun. I think that looking at actual products of it are the most telling indicator. Frankly, they have some pretty good stuff! I really liked the “Front End Handbook”. The only formatting boo-boo they have is that in the PDF format, where you really don’t want your first page to be a book cover. Just want the title and get to the clickable menu.

I actually feel that forum software can be a very good documentation platform. Not all of them, no. Earlier today I was having issues finding one of my own posts. The real issue is that even with a category>category>category>thread capable software, people never seem to take advantage of it. Also, the mix the discussion forums with the documentation sections. That creates a mess. Rarely do you find a forum that is well implemented in a technical writing standpoint.

We could have your app mounted at some other point other than / and have ehr.librehealth.io be documentation. This is how toolkit.librehealth.io will be.

I want to share some experience that my students are facing with the documentation as a repo or branch, is that they need to know git well and understand squashing etc. I think this raises the bar for contribution and shouldnt be necessary. We might still be able to use gitlab CI and gitlab pages to deploy it, but I think using the gitbook site and its editor interface (and its very nice desktop client) is very intuitive for users. No other documentation site, like read-the-docs or mediawiki or confluence have this intuitiveness. We should make use of this user-friendly feature of gitbook, and so I suggest the following:

  1. We make a gitbook org for librehealth and put all the documentation repos in there.
  2. We sync those to gitlab repos that will use gitlab CI and post to gitlab pages
  3. People can read/printpdf/tweet the books through gitbook too. This in some sense makes point 2 above redundant.

Does anyone have a better suggestion? If everyone agrees with this, @vchilkuri @phoenigmatic can we go back to using your gitbook-hosted site and I request you to transfer your repos to the new librehealth org that we will create there.

2 Likes