Effortless Documentation with Modern Tools

This is a long article on The Surprising Power of Documentation and I think it’s worth a read, but it’s also geared toward implementing a documentation-first mindset in an organization.

This isn’t something I’m concerned about focusing on in this post but there are a few points the articles are makes and it reminded of a few things that I’ve done over the few months – especially with the growth of tools such as GitHub Copilot Chat – to make the documentation process almost effortless.

Effortless Documentation

One of the things I consistently recommend to others when working on a codebase is to document their classes and/or functions even if its just for the work they are introducing.

With the sophistication of modern IDEs, there are more arguments for why it’s harder to avoid documenting your code than not doing it. In other words, with the right IDE or IDE extension, it’s intelligent enough to analyze your functions, their arguments, and determine:

The function’s visibility,
The parameters list,
The return types.

And if you enhance it just a little bit with tools like GitHub Copilot, you can ask it to describe the code within the function. Then you can use that output as the function description. It’s almost like being able to generate effortless documentation.

Providing this much information and context to fellow developers can make working with the codebase so much easier.

Pay It Forward or Do Your Job

Think about the last time you were able to obtain the information you needed from the codebase’s documentation versus when you had to dig through the code to figure out what’s going on with it (that is, “why isn’t this doing what I think it’s doing?”).

I don’t know if it’s more like paying it forward than just doing what we should be doing (or maybe it’s both), but 16 years into this career, and it’s still something we could be doing better.

Recommended Tools

Far too often we say this is something that’s part of the developer’s job but then not do anything about it. So in an effort to make it easier for those of you who are using Visual Studio Code, here are the tools and extensions I recommend:

I’m sure there’s many more that can help, but these are the basics that can get you started based on the content in the post;