Small effort big impact

I love when I find these areas because they are a win-win. The project/company/software etc wins from your impact and you win because it takes a small amount of time.

Today I want to tell you how I handle documentation for a software project. What I have found is little efforts in the documentation have an outsized impact. I cannot a scenario where someone says no or rejects your pull request containing documentation updates. For large projects, internal or external the value gained is enormous. For me, this advice applies more to documentation for stuff at work rather than hobby projects. However, honestly, good docs are such a great asset to any project regardless of size everyone wins from having them. Feel free to take pieces of this knowledge and use it in your own projects.

How I approach creating great documentation:

1. Take care of what you do have
2. Enhance what you have
3. Reorganize into the preferred formats
4. Repeat

Take care of what you have

Documents typically are not on the critical path to deliver code and features. They tend to fall behind and become stale. Having no documents absolutely is the worst but having incorrect and outdated documents falls close to it. How bad can this get?

I once had almost a three-week onboarding to a job to get to a point where I could build everything locally and run their setup. It was awful I felt crappy for not being able to solve these problems and the team suffered from the time I theoretically should have been ramping up but could not. The software, technologies, frameworks, were brand new to me and I had no idea why things failed. The team was behind and onboarding me fell behind on priorities.

As a new developer even if you don't understand everything you can write excellent notes and update the existing documents. At this step, I hesitate to change anything in terms of format or documentation technologies but make your motto to bring it up to date. You have to get going anyway so why not spend a little time /effort and have it benefit you and all future team members.

Enhance what you do have

Once your documentation is up to date, next I like to look for any changes I can make to enhance what exists.

Examples:

• Adding images of screens/configurations
• Creating simple diagrams to document complex flows or architectures
• Updating structure so it flows better
• Linking to other documents you found helpful
• Adding code snippets/formatting to commands
• Add a troubleshooting section / do this when this error occurs

A lot of times in large corporations, documentation exists in multiple places and it can be hard to find. As someone new, you might not know where to look. Never doubt the value of adding links to alternate places to show what's next.

Re-organize

There is no one 'right' stack of documentation. I prefer and advocate for:

• Concise README's
• An accompanying static site (something like docusaurus)
• Everything else in a wiki (like confluence etc)

At this step, I recommend surveying what is out there and figure out your ideal standard. You might not be able to change the entire organization but hopefully, with good ideas, you can convince the powers that be for this project can we shift things around. What I love about the static sites is they are easy to set up and usually come with a decent theme to get started. You are not proposing days of work but minimal effort maybe an hour or two.

At this stage, it is important to note you need to figure out what goes where? Is your README too bloated? Should some data move from the wiki to the static site? Every option has pros and cons and guidelines would benefit the entire team so they stay within the new standards for your project.

How I choose to define these documents:

README

• High-level overview of repository/purpose
• Up to date instructions on how to build and run
• Link to static documentation

Static Site

All the good things for a developer to know to run locally that don't fit in build instructions.

Examples

• DB setup guides
• How to point to other environments
• Gotchas
• Where to find app secrets (don't store in the document)
• Testing setup and running locally
• How to test manually locally and test users if necessary
• Known issues
• Troubleshooting ideas for local
• Links to wiki

Wiki

This should have the high-level project and system architecture documents. I expect lots of diagrams/flows related to how various repositories interact. Cloud/networking diagrams. Everything that is important but perhaps too broad to fit alongside a single code repository. Project history, project structure, team members, org chart of project leadership/team members for new joiners.