Welcome to Tanuki Tuesday, where I look at the features offered by GitLab. Up this week, knowledge sharing in the form of project Wikis.
Most people will already be familiar with the concept of a wiki, courtesy of Wikipedia and the mass contribution ethos it has. But why would you use a wiki for a project?
Documentation. It's one thing often forgotten in projects, shoehorned into a massive README.md file, or something which developers hope the community will create later. Why? because it's yet something else to design ahead of consumption.
It doesn't have to be!
The wiki feature within GitLab projects provides a useful space to put your documentation. Better still, the content is built using markdown. If developers can contribute to the README.md file, then they will be able to add the content into the wiki.
Getting Started
If you've not got a wiki for a project yet, navigate to your project and select the wiki option in the left-hand menu (of, if g->w if you use keyboard shortcuts) and click the 'Create your first page' button.
This will take you to the page edit screen, where the title will be pre-populated to get you started with the basic home page. You don't need to create the home page straight away, but any time you visit a wiki which has some pages but not a home page, you'll be shown the 'Create New Page' screen for the home page.
What are the benefits of a wiki?
Because the wiki is a separate git repository of its own, it is not checked out at the same time as the project source. This reduces the amount of data needed to be downloaded by anyone cloning the project. It has the added benefit of your project commit history not being clogged up with typo fixes and additions in the wiki, leading to a cleaner commit history for code.
This has the added benefit of allowing small, single word changes to be done without it forming part of a code review on save. Similarly, the repository can be checked out and back in to allow larger scale changes take place outside of the slow nature of editing online. This is particularly useful if there's a mass change of locations to be done.
Each page then gets its own history of changes to be fully transparent about who changed what, and when.
There's no need to design the layout. Sure, great looking documentation looks, well, great. But design resources are often limited. And documentation should be useful and easy to find above all else. By using the wiki the documentation can be produced in a consistent manner from the outset.
Conclusion
If you don't have the time to set up your own documentation site, or to design one, then simply start with a wiki. You can still have useful documentation which develops organically with your project, and is still closely linked to it. In most cases, some documentation is better than none. So create some!
If and when you have the time to design and build a stand-alone site for your documentation, you'll have all of the content you need to get started. It's less of a daunting prospect because it won't be created from scratch, or need someone to understand how things work if they don't already know.
As usual, the GitLab documentation provides a great insight into how to use the Wiki feature, and even how to customise the sidebar menu.
Top comments (0)