Afterword: On Documentation

My view on documentation is that everyone appreciates having it, but few people enjoy writing it. Documentation comes in many forms: source code and tests, project manuals, command-line help, blog posts, videos, books, and increasingly, information assembled and presented by AI. Whatever form it takes, somebody has to explain how things work.

The interesting thing about writing documentation is that it forces you to look at what you have created from somebody else's perspective.

I am a firm believer in ease of understanding and implementation over architectural purity. Something may be technically elegant, but if it is unnecessarily difficult to use or explain, perhaps it isn't quite as elegant as you first thought.

Writing documentation can be a grind. There is the book or user guide, the application's interface, the command-line help, the repository's Markdown files, and all the other places where things need to be explained. Every new feature can mean revisiting several of them, and every change risks making something else out of date. It is not difficult to see why documentation often falls towards the bottom of the priority list.

However, writing this book has taught me something.

Having to explain how Snug works, particularly to someone who may never have packaged a Java application before, has made me reconsider parts of its design. Explaining the command-line options, the runtime installation process, and the messages presented to users has prompted changes to both the documentation and the software itself.

When you have to explain a decision, you get another opportunity to question it. You start asking yourself:

• Why did I choose to do things this way?
• Could it be simpler?
• Would somebody else understand how to use or configure it?
• Is there something missing that would make the experience easier?

Documentation also makes it harder to overlook gaps in functionality. Sometimes a feature is missing for a perfectly good reason. Sometimes it was never considered. And sometimes you discover that something you thought was obvious is not obvious at all.

That does not mean every possible feature should be added. Quite the opposite. Being able to explain why something has deliberately been left out is just as important as explaining what has been included.

Throughout the writing of this book, Snug's code, features, and behaviour have changed as a direct result of trying to explain them. In several cases, what began as an attempt to improve a paragraph ended with changes to the application itself.

Naturally, those changes meant rewriting the paragraph. Again.

I believe Snug is a better product because of this process.

So, if there is one thing I would recommend, it is to write about whatever you are building. It does not need to be a book. A simple HOW-TO, written for somebody who has never seen your project before, is a good place to start.

You may find that the hardest parts to explain are the very parts worth reconsidering.

And that, perhaps, is one of the best reasons to write documentation in the first place.