What's a documentation?
Documentation is just a way to help other people understand something that you did, and learn from it. To do that, we propose that you use Gitbook.
Gitbook is a popular tool that "makes it easy to write and maintain high-quality documentation". Technically, it's a piece of software which is both open source (meaning that you can install it and use it on your own computer or server), and is also available as a service on Gitbook.com.
Basically, Gitbook takes formated text and transform it into a small website that you can browse like a book (hence the name).
This way you only have to focus on the essential: the content. Gitbook takes care of the rest for you: formating, making a nice interactive website and all that.
Digital Transport for Africa maintains an instance of Gitlab which allows you to host, publish and share all sorts of resources: code, data, text and static websites, which means - you guessed it - that we can host Gitbooks (thanks to Gitlab Pages and Gitlab CI).
How does this work? Can you show me an example of a Gitbook hosted on Digital Transport for Africa?
You can find the basic template here. What you see is a repository with files in it, the "git" part of the name. It contains mainly the raw content of the documentation: a
README and a
Gitlab then deploys this as a small website: the "book"! The content of the
README forms the content of the page, while the content of
SUMMARY makes the left column a table of contents.
Note: When you change the content of the git repository, the book is built automatically You don't need to do anything but editing content. Also, the book's domain name (digitaltransport.io) has to be different than Gitlab's (digitaltransport4africa.org) for security reasons (cookies and stuff).
How do I need to format my text?
How can I create my own Gitbook?
You don't have to understand the technical details. Here's all that you need to know:
- Choose a template that you like, such as the one above.
- Fork it! Click on the button at the upper right corner. Then, select your space (where the git repo will be copied).
- Edit the content of the
README.md(which, by convention, will be the first page of your gitbook) by clicking on it in the list of files, then clicking on "Edit" in the upper right corner.
- When you're finished, click on "Commit changes" at the bottom.
- That's it! Your first page is done, and it will now be deployed as your own gitbook. Go find it by opening this URL in your browser:
<your namespace>.digitaltransport.io/gitbook(with the namespace being most likely your Gitlab username, the same that appears in the URL of your repository).
Things you can do next: 6. Add other pages to your book by creating other Markdown files: click on "New file"
Then, add your text (just as you did at step 3 above) and don't forget to type a filename ending with
.md. Rince and repeat for each new page of your book.
7. Don't forget to also update the
SUMMARY.md file by adding each new page.
Note: You can also clone the repo locally and edit the files on your computer with your editor of choice, then pushing each changes to the repo.