Extensive documentation is time-consuming, but relatively simple to create.

USEFUL documentation is potentially time-consuming, and can be difficult to create as well.

My approach to documentation (the tl;dr):

1. Record what challenged me personally about a problem.
2. Fill in background gaps.
3. Add gory details as addendums or links (depending on stability of source documentation)
4. Organize so that someone with very little time or attention span can find the important parts first (or linked). Highlight and callout important bits as your documentation platform allows.
5. Publish it where your target audience will actually be (might be markdown in GitHub, might be a Confluence wiki, might be a Word doc/PDF sent for onboarding)
6. Curate your documentation links and links to supplemental documentation as an iterative process.
7. Iteratively edit your documentation as you revisit for your own purposes.

Some challenges with creating useful documentation

• The subject matter is too broad to cover in a clear and concise way.
• You don’t know the subject well enough to document.
• You’ve created documentation but the repository that it will be stored in will guarantee it is never found.
• The subject to be documented undergoes regular changes that quickly make the documentation out of date.

Subject matter too broad

The solution to this is to take notes on specifically what challenged you. If you had to spend time discovering those things, someone else likely did too. By focusing on what was relative to you, you create potentially more useful documentation for others.

You don’t know the subject well enough create useful documentation

There is a sort of imposter syndrome lurking that assumes that everyone else knows more than you on the subject. While this may be true for people already experienced with a subject, it’s far less likely to be true of new members of the team, especially if they have less experience than you overall. The likelihood that there’s zero benefit to others is slim, and by documenting and explaining things, you solidify the knowledge your own mind.

You’ve created documentation but it may not be found

Document in a location where other documentation can be found. Or if you’re documenting code, document or link from the code or README. Create links to the docs from other docs.

The subject of the documentation regularly undergoes changes

Build time in the task to update documentation. I know it seems like you’re not “being productive”, but, in reality, adding/updating documentation can easily be more productive than the task that it is paired with. By documenting or updating documentation, you are magnifying your efforts across all of the people who come after you.