What do you do to motivate yourself to update documentation? I have so much of it that it is now a significant undertaking to keep it up to date with the tool, and I am losing interest. I'm trying to figure out whether I should just tag most of it as out-of-date and come back to it later when there are enough users to justify it...
My complete lack of motivation for updating documentation makes me very motivated to find solutions to minimize the amount of documentation needed.. 🙂
I don't know the context here, but I can throw out some thoughts:
- Writing docs forces you to spell out how your project works and what it does. It can help to deepen your understanding, and highlight confusing areas. Even if nobody reads it, it can be a helpful exercise.
- It's ok that docs aren't perfect. Sometimes there are other things to prioritise - so raise an issue on the repo like you would with any other bug. This can also help to prompt help from other people down the line.
- There are lots more docs generation tools nowadays that might help speed up the process.
- "What comes first - the users or the docs?"
- A lot of docs are very dry - can you make them in a format or style that's more fun for you?
- What kind of docs suit your project best? To-the-point reference? Just some examples? A tutorial? A blog post?
sincerely,
someone who loves writing docs
FYI - brainstorming - I’m playing with Obsidian (markdown) and Descript (video editing) and Just Press Record (AI transcription of audio), searching for ways to reduce the boringness of creating documentation after-the-fact. On my wishlist to understand better: iMovie, Da Vinci, OBS, Loom, “howto interview” (towards “interviewing myself” to get technical points across), etc, I’m also playing with drawware (tech diagram compilers) to reduce the need for documentation.
<puts on professional documentation person hat>
I think a key to most great documentation is that it does 1 of the following, and doesn’t try to be everything for everyone all at once. It picks a lane, and runs with it:
- Tutorials, learning-oriented (teaching someone to cook)
- How-to guides, problem-oriented (a recipe for cooking a specific thing)
- Explanation, understanding-oriented (historical overview of an ingredient’s cultural importance)
- Reference, information-oriented (an encyclopedia article about an ingredient)
Each of these types maps fairly well to an audience:
- Tutorials are for folks who are totally new to a thing
- How-to guides are a step up from tutorials and help you learn idioms and best practices of a space
- Explanation is useful when needing to convey the value of a thing
- Reference is generally for experts who are cozy doing the thing
When you are writing your docs., are they really descriptive? Do they have a specific audience(s) in mind?
Having a clear idea of your “ideal documentation reader” in mind, can help keep them manageable, since it can let you focus on not having to documenting everything and instead just what’s needed for your goals.
</doffs documentation person hat>
Wow. Exceedingly helpful replies, everyone, thank you. My documents happen to be divided more or less exactly as you suggest, @Eli Mellen. And Paul Tarvydas I'm using OBS, and getting into gifs, because the tool is so visual. Lu Wilson I'm going to see if there's a way to have more fun with it! Thanks for the suggestions!