Have you ever looked at a section of code and thought:
- This seems vaguely familiar, but I don't know what it does.
- I don't know why it does it that way.
- This is wholly unfamiliar, and I can sort of maybe (probably not, says the critical sub-conscious) see the scope of 60% it touches?
Yeah, that's been a lot of my developer experience.
My first job was working with an undocumented and uncommented custom PHP framework. I was very inexperienced with PHP and learned to read code to figure out how things worked.
My second job was WordPress and Drupal focused. They both have huge amounts of documentation, blog posts, books, etc. That was a starkly different experience. I appreciated the balance between being able to find answers to my questions then getting to questions that didn't have answers and being able to dig into those answers myself. I was more productive and could still push myself into places I wasn't very knowledgeable about, especially after I became more familiar with relative basics.
When I took my third job at EasyRx, a different aspect came into play. There were systems and developer knowledge that had built up over years, and they weren't written down anywhere. That's not entirely true, we can search Slack and Jira for contextual references, there's still the code, and there was one complex aspect that had documentation written in a file. Even so, there was a large amount of code and processes where only developers knew the details.
As I started coming up to speed with our development process, I took notes. From how to install and set up a local installation of our app to random bits of info that I had to ask other developers about and new features I was implementing.
At some point, I found myself referencing my notes to answer questions. I’d create a pdf out of them and then send it to someone or post it in Slack. In the moment it was helpful, but not in the long run. Slack files get lost in the noise, or I end up handing out information multiple times.
I decided it would be more helpful, and fun, to set up a developer documentation site.
How I implemented it
I did some research on options and decided on Facebook’s Docusaurus. It is specifically for documentation, has built in themes (and dark mode!), and content can be created with Markdown.
Having markdown as how we write our documentation gives us flexibility to try other frameworks or no framework at all.
There are two git repositories. One for the Docusaurus install and one for the markdown files.
The markdown files are stored in a separate directory and the Docusaurus directory has symlink to the markdown directory.
We can all edit the markdown files in whatever type of editor we want.
I have a bash script which builds the static site and pushes it to where the site is stored on one of our servers.
The site itself is locked down by an htaccess password.
I generate the sidebar dynamically based on the directories and files in the markdown directory.
Now, when I need to reference something I’ve made documentation on it’s just a simple link. It’s come in very handy for getting new developers up to speed and for my sometimes forgetful brain!