Making a project, library or package sometimes seems like the hard part, but if you want someone else to use it you probably want to spend a decent amount of time on the documentation to help others get started using your package. People won’t know how to use a feature if you don’t even take the time to write about it as they won’t even know it is there.
So what are the different methods of writing documentation?
Readme
A readme is the best place to start. A readme is normally a one page summary of the key features and how to get started installing and using your project. The readme is important as it is normally the landing page for your code repository on GitHub so try and make it succinct and to the point.
A readme is normally written in markdown format so allows for basic formatting, such as headings, paragraphs, tables and code snippets, so make sure you add code examples where required.
If your readme gets quite long then try and a contents section with links to the headings and subheadings to allow the reader to quickly jump to the section they need.
If your readme gets too long and you need to split it into separate pages, then where can you go next?
Wiki
If you are looking for a quick and easy solution then why not use a wiki. Most git hosting services allow you to turn on a wiki and start writing pages. Like a readme, a wiki usually allows markdown format, as well as links between pages. Check with your git host as to the type of markdown they use and the best way of linking pages together.
Start with a contents page with links to other pages and try and ensure there is an easy way to get back to the contents page or to continue to the next page of the documentation.
If you are happy with a basic but functional docs site then you can stop here, but what if you want to include live examples, such as CSS or JavaScript examples, then a wiki just won’t cut it.
GitHub Pages
If you want to make a more custom site with in line examples (not server side code I’m afraid) then you can use GitHub Pages to host your project site for free (other alternatives are available, such as BitBucket pages).
GitHub pages allows you to either make your own html pages from scratch or use Jekyll. If you use Jekyll then it will build your html from your markdown files when you push up to GitHub. If you make your own HTML pages or use an alternative static site builder then you will need to compile the HTML on your local machine and then push up the compiled HTML, CSS and JavaScript.
I personally use Jekyll to host my sites and projects, but I have also used VuePress in another situation to compile markdown using JavaScript. VuePress also allows you to use your own Vue components if you wanted a way of showcasing them.
If you do go to all the effort of making a dedicated site for your documentation then you will want to let people know that it exists. As stated above, GitHub pages only allow frontend code but it also allows you to use certain Jekyll plugins (if you are using Jekyll) to allow some additional functionality, such as a sitemap, seo optimisation and an RSS feed, to make your life a bit easier and make your site more visible to search engines.
One final thing is to ensure you add a link to your documentation site from your GitHub repo description and in the readme as well. This will allow people searching for your package to find your documentation site, as well as the code in GitHub.
Top comments (15)
Its always good to put in one place, we use dacasuarus at Jobbatical for most things.
Good points! It is very relevant to remember that there are different documentation types. Also, I really like that your listing maps so well to the categories from one of my favorite articles: divio.com/blog/documentation/ I guess you may like it, and @chrisrhymes too! :-)
I hadn’t heard of docasaurus before. I’ll check it out!
I think Docusaurus is open source project for Facebook, not Google.
Yes, by Facebook. Will edit my comment. Thanks
Our (the company i work for) go to place for all of this is Confluence.From documenting Meeting notes to Release notes, SOWs, Wiki,HowTo Guides, Functional and Technical documents. Everything in one place yet independent from each another.
Great idea to put everything in one place. Much better than searching multiple locations.
Fantastic article. I recently did some research for a presentation about open source docs and here were some key takeaways. Some are much in line with your suggestions. The readme was equally as important as the website.
And some more developer specific ones were that 1) you can just publish the readme also as the website as a MVP with one click from github 2) that wiki's were a waste of time 3) you should pay close attention to he content of the readme as well as making sure it is accessible.
The github page for the event has more info on good documentation practices, but also tries to apply them in github as well.
So the counterpoint in my daily consulting work is that the reality can be far from these ideals. One thing that is nice about open source is it gives you a way to practice best practices out in the open and gain experience and feedback. And sometimes it is about looking for small wins that will help the team short, medium and long term. Rather than some large rewrite.
Try to avoid the no docs / just read the code mentality. Use the "what if person x got hit by a bus" reasoning to try to create a way that the basics of the operation can be restarted and built upon. This will help not only in an emergency situation, but also onboarding new developers, increasing visibility with stakeholders, and allowing others on the team (for example designers) to deepen their understanding of the project.
What is your process to make sure the documentation is up to date with the codebase? I prefer to keep documentation on implementation detail in the codebase itself (MD files). This way a documentation update can be part of the code review and are always in sync with what branch you are working in.
Good point! It’s always important to keep documentation up to date.
One thing you can do if you are using github pages is to create a docs folder in the project root and configure the settings to publish the page from there.
help.github.com/en/articles/config...
I really miss 'code' here.
As soon as developers are the target audience of the documentation, I have found that docs written in a wiki, Confluence or other external documentation tool always become outdated. And not in a year but rather one or a few weeks. Either it takes a lot of effort to update the docs or nobody will read them anymore.
Documentation in code solves this. A search for a code term also shows documentation. Whenever you open a source file with docs, it it easy to (also) update them in a PR. There are many tools for most languages to (auto) process docs to HTML or PDF form for distribution. And most importantly, the meaning/context/design of a model is clear the moment you read the code.
Of course, some documents are more drafts and should not be included in code. But even drafts and design documents can be included and removed/updated later. Especially because many documents are written in markdown so can be embedded in the relevant source file (often a model or root aggregate of a model).
Source code is the best documentation, dammit.
github.com/EnterpriseQualityCoding...
Is it though?
EVERYTHING can be misused. That's why they say drink responsibly.
Thank you for the link, this is awesome ;)
You're welcome :)