The recent WordCamp Phoenix was once again a vibrant, community-focused event that was packed with useful content and friendly people.
I was thrilled to speak on stage as a software developer to a great crowd of my fellow WordPress and engineer peers about documentation from a developer’s perspective, and how documentation has evolved over the last 30 years.
Now, I’m sharing my slides here in hopes to help the wider community as a whole.
With so many open lines of communication in our modern-day workspaces, I discussed my strategies for stemming the flow of information. As a fully remote team at Pagely, like many engineering teams, this is fundamental to the way we work effectively.
My slides are packed with actionable information on my tried and true methods to ensure that workflows, bug reports, and other issues are appropriately documented whether you’re part of a large team or are working on your own.
The long and short of things are here below, and check out my whole slide deck for more.
Code is Constantly Changing
This means documentation needs to function more like a living document instead of something that is written once and forgotten about.
The constant battle I see is how challenging it can be to maintain docs and, in any stage of a process, that documentation may need to be constantly updated. Making doc updates is critical to managing lost time in the future, be it by users that are new to the project or by future maintainers.
We need to accept that the environment we work in is constantly changing. We need to embrace it. And we need to leverage it.
Rules to Live By as a Developer
Start simple
Lower your barrier to entry by starting simple. Create a single document that you continually add to.
Creating a new project? Include a README file right from the start. Explain the purpose of the project.
Document as you go
Once you start, think about using your breaks in writing code as moments to document. I think of it a bit as a recipe that you’re testing and tweaking. What are my ingredients, aka dependencies? Do they interact in unexpected ways with other ingredients? If someone wanted to add to your recipe, or use it in their kitchen, what would you tell them so they had the best chance of succeeding?
As you add in complexities like Unit Testing and Deployment methods, update the README.
Comment your code: note where your projects and processes live
Even developers who believe in writing human-readable code need to clarify what’s happening to ensure their code is accessible to other devs.
These rules apply to managing projects and team workflows as well:
- If you’re on a growing team, consider creating one collaborative document where you note what tools you utilize. Explain how you use each tool.
- Does your team have discussions on Slack? Consider copying links to discussions into a separate space if there was a thought process that future team members will need to know about.
- Do you have a preferred task management tool? Note that tool and consider explaining how your tasks are organized.
- Do you look through tasks weekly? Take them as they appear? Take note, and share.
You Decide What You Want to Support
Moving toward handling documentation along with outside influences like PM’s, or users, or contributors… decide on a hub you want to focus around, and decide on a workflow.
Say you’ve got a Team Slack and a project repository that lives somewhere like GitHub, GitLab, or BitBucket. Determine the primary flow for information and where you want to manage the project.
My ideal project is set up with GitHub issues holding the plans for my project as well as handling bug submissions and feature requests.
New Feature = New Documentation
As you continue working through your project, continue adding docs as you add features. Once you start noticing you need more than one page of docs, and that you’re outgrowing your collaborative Word/Google doc or your project README is getting too long, consider what solutions can grow with your project.
Since you’ve already started a README for your project, expand on that first by adding a table of contents and sections for the details of your project, like how to install locally. There are some fantastic examples in the WP space already — check out the WP Tide project.
I personally like to avoid breaking docs out into a repo separate from the project until I’ve found a specific need for it — usually if I find I’m starting to break README items into subsections, or wanting to add more “pages” or directories to organize my docs, then it’s time to split out a separate docs site.
Create & Share
Help people work within the workflow you’ve established. Documentation for projects and workflows go awry when you stray from what you’ve worked so hard to establish.
My current team utilizes GitHub as our primary source of stored information.
We utilize our specific team Slack Channel for any related discussion and use a workflow that puts discussion and notes directly into GitHub issues for project tracking.
For smaller projects, this exact workflow does just fine — we can link to Slack discussions, we use GitHub issue templates, and we’ve got README’s explaining how to utilize the tooling built into projects like Unit Testing or Database Migrations. We even expand upon the README concept a bit as needed and add additional KNOWLEDGEBASE-type files in the case of a non-public project to keep it simple.
But that’s all fine and dandy when we have a project that only our team needs access to, and we already know where things live in the code to reference inline docs for — say— a REST endpoint… but what happens when we have a feature request from the Support team?
We ensure they can stay in the loop by piping all of our important GitHub activity back into a specific Slack channel:
- this silos the information so it’s not constantly interrupting the conversation, but makes for an easy date-based reference for when things are happening.
- the same goes for releasing code — we document right within GitHub including release details, and that data is piped into Slack for the rest of the company to see on an as-needed basis.
If I can leave you with one important parting thought…
Good Documentation Comes from Those Who Build and Use the Product
Good documentation comes from users & devs (not technical writers).
As devs, we are empowered to utilize tooling to make our documentation write itself by using auto-generation tooling and integrations between services. We have GitHub Pages to keep docs close to where we store our code, we have issue trackers on the three main free Git services — GitHub, GitLab, and BitBucket all have ways for storing information about the progress and details of a project.
And we still have the ‘ole reliables — a simple workflow documentation can be started in a text file and shared between peers via Google drive or even by publishing a basic WordPress app — something I think most of us could do without too much trouble.
Writing docs has never been easier, especially when compared to the dark pre-internet days of the 90’s.
In that, there’s no reason to not have software documented by the people who write it and by those who use it. A big departure in the “then and now” comparison is that back in the 90’s, there were no communities and teams collaboratively working on docs.
As always I would love to hear about your documentation processes. Shoot me a note about it in the comments and let’s keep the conversation going.
