Since March, I've looked at a lot of documentation. Countless mini projects to develop my technical skills have led me on expeditions upon which I've encountered other's work. Of the libraries, frameworks, plugins, and packages I've either attempted to implement or am working with currently, it's amassed to a great deal of my time spent on making sense of documentation.
From this time spent, I've gathered a number of features from a variety of documentation that have been much appreciated or left me more confused. The following is a collection of those features, particularly those that make the documentation more difficult to follow.
1. Disorganized content
There needs to be some sense of hierarchy in any documentation. Very rarely does one need to go through everything that is written. Rather, developers know what they are looking for and want their eyes to be guided to an answer quickly. Some suggestions to create a hierarchy:
- an introduction for context in case someone came to this code through a random link in the web
- make clear what parts of the page are related with some form of grouping, either with a heading or sectioning off with a divider
- keep things predictable - place recurring elements on the same parts of the page (ex. images always on the right or left)
2. No examples
Show 👏🏽 me 👏🏽 what 👏🏽 you 👏🏽 mean. This is my callout for all things documenting software that involves UI. Provide examples of what your feature looks like in action. If you can't host it somewhere, at least insert pictures of it. Each new section or feature in the documentation should have a clear demonstration of what this should look like if implemented correctly.
3. Not providing alternate ways of implementation
Now that we've addressed including examples - don't give just one. It's unlikely the one use case you came up with will fit everyone who uses your tool. It's also impossible to predict all use cases, but it's considerate and awfully helpful to offer at least 1-2 alternate ways of implementing what you've built in situations that differ from what you'd expect. Get creative! Think about how the feature might fit into the header for a website. Will it work well on mobile? How will it be used in React? In plain HTML?
4. Convey your idea through various mediums
There are so many ways to show what you mean. Don't stick to just text! Express what your code can do through a video tutorial. Show how you can interact with it using a GIF. Embed the tool into a Codepen for others to play around with. Create a template on Glitch that anyone can remix to get a feel for how it works.
5. Assuming too much
If you've been in the weeds of the code for months, a lot of how it works is probably going to seem obvious to you. So when you write the documentation on how to use it, it's important that you run it by various audiences. Of course, some background knowledge can (and in some cases, should) be assumed. But the more you write the documentation with some prerequisites of tribal knowledge, the less developers will feel encouraged to embrace it. There are those in your team that may be in the weeds with you, or at least in the field you are building for. Yes, you are writing for them, but you may also want to consider writing for those whose developer journeys began a bit later by providing bare-bones use cases. One of the best examples I've seen of this is in JavaScript's explanation of how Promises work. It reads like a story - at one point I forgot I was reading about code but I walked away with a clear understanding of a topic I was once unsure about.
6. Stagnancy
Make sure you keep your documentation fresh. At least, as long as you are making changes to a project the documentation should reflect that. Don't let too much time pass between these updates - make it a habit for the changes to happen simultaneously. You don't want to leave a developer confused as to why something didn't behave the way it was outlined to behave when they followed the steps exactly. An argument for stagnancy could come if you're ready to let go of a project or it's reached the peak of its experience. You may not be sure how it can be improved, which leads me to my last point...
7. Open source your worries away
Some projects choose to document everything on a ReadMe, some may make a separate site entirely. Whichever the path you choose to take, allowing other devs to submit or at least suggest edits will only lessen the time you have to put into maintaining documentation. The diverse development experiences of others can help you see gaps in your thinking that may not seem immediately apparent. They can shed light for other developers who might be using your feature in similar quirky ways you could never have anticipated for.
Closing Thoughts
These little considerations when added up could make a huge difference for increasing both the quality of your project and the number of people that choose to work with it.
Let's all do our part to make the coding world a little less intimidating by bringing clarity to our work 👩🏽🔧
Cover photo courtesy - Frustrated office worker.
Oldest comments (0)