This conversation comes up so regularly, I just call it Old Faithful. Here's my youngest, standing in front of the geological wonder, back in 2013. Now she's a teenager with a car and a job!
This old, faithful conversation is about documentation. "How much documentation is enough?", we asked in the pre-pandemic world. I won't give the answer away here.
But how can you even get close to the right answer of how much you should document, if you don't have a place to start. That place should be your application's wiki.
Documentation Files are Immediately Out of Date
Not a lot of people are plugged into the dirty underworld of documentation like I am. You know Macroscope documents by their numbered codes? Ever worked Documentum? It's a harsh world out there.
Let me ask - where do your documents go once your system has been implemented? Mine live as a dead archive on a Sharepoint site that nobody will see again. Maybe you have a basic file share.
When the requirements pivot, who's responsible for going back into the Word docs, creating a new version, getting the appropriate approvals, and re-releasing them to the archive? I honestly hope that no one has that responsibility.
It's Waterfall vs Agile
Legacy software teams work on a waterfall system. Over a period of months, various team members will develop the documentation, plan the work, execute, test, and deploy. The documents in question here tend to be heavy because they have to prepare for any scenario. It's common to deploy changes quarterly or annually.
In the Agile world, we iterate, execute, and deploy in a significantly shorter loop. Production deployments can be daily, maybe monthly at worst.
The Bottom Line: Standard documentation is a slow boat to obsolescence.
Documentation Files Are Insufficient
How do you document cross-cutting technical concerns in a Word Doc world? I'm talking about abstract cross-cutting concepts; the things that don't typically get documented, but are critical to operations. You would have to draw up numerous documents for each one. This isn't just uncommon, it's borderline insane.
- Sessions What constitutes as a login. How long until an idle user is logged out. What happens on an idle logout. What's the justification for that length of time.
- Logging How is it collected. How much logging is right. What types of events are tracked. How do developers create logs. How does an analyst read the data.
- Caching What mechanisms are used. What needs to be cached and why. What limitations does the cache have.
- General Domain Knowledge What is the application for, and how do we accomplish that specific goal. How do we contact clients. How do we communicate messages to users.
- Common Troubleshooting What parts of the application are likely to need help. What are the user support frequently asked questions. How does user support work.
- Scheduled Tasks Are there any scheduled tasks. How are they scheduled. Who has access to it. What considerations need to be made before people touch it.
- Testing How to find and run the automated tests. What is the spirit and mindset of the testing initiative.
- Deploying How does the application get deployed. Where does it go. What are the steps.
- First-Time Setup How does a new developer get acquainted with the application. What tooling software does the team use to build and support the product. How does a new developer get the code, the SDKs, get it running, and successfully make production-worthy changes.
- Teamwork What is the team meeting cadence. How does the team communicate.
- Technical Debt What standing issues do we know about. What are things we are and are not willing to fix.
All of these types of information belong in a wiki.
Wiki Mindset
A wiki is collaborative, team-editable, living, and can be constantly updated as often as things change.
Sometimes a wiki is oddly specific. Sometimes it is imperfect. Hopefully it is very human documentation, complete with mentally mapped concepts linking to each other and half-thoughts scribbled down with references to remember later. This is tremendously valuable. Some parts of a wiki may be well organized. Some parts could feel chaotic.
Most of all, a wiki solves the problem of where to put information about a system.
While it may seem like I'm describing an unstructured heap of random text files, let me remind you of a few things:
- Modern searching software can bring organization to any wiki that may seem messy
- A little organization goes a long way
- You probably don't have a different plan for miscellaneous-yet-critical documents
Wikis are the Agile approach to documentation. It gives the team the ability to document in sprints and provides space for free thinking and idea sharing.
Getting a Wiki
Sourcing a wiki for yourself could be as simple as opening a project on GitHub and enabling the wiki setting. It's free and straightforward simple to use. I use a self-hosted Gitlab with the same feature.
But you know what works the same as a wiki - same strengths, but some new ones as well? That's a docs-as-code solution.
Docs as Code
There's a new push at work for Docs As Code. You may have heard this, it's not unique to me, nor to Boeing. I think it was coined by writethedocs.org who said it eloquently enough-
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:
- Issue Trackers
- Version Control (Git)
- Plain Text Markup (Markdown, reStructuredText, Asciidoc)
- Code Reviews
- Automated Tests
I would add CI/CD to the list. Also, light programmability -- adding a little unique interactive component inside your documentation can really bring it to life! I wrote a few small Vue components; things like:
- Microservice uptime checks like a video game service
- Generate database connection strings based on servers and environments
- Format text in a particular way to announce a new feature flag
- ... and a handful of others that are cool but not cool enough to talk about without architectural diagrams to explain why they were necessary but also kind of just fun
Added Strengths
Docs-as-code websites are just as editable as a wiki. The content files are all markdown and backed by a git repo. But that's not all.
Docs-as-code websites can look better than a standard wiki. They will perform better. They can provide searching capabilities. They can be far mor extensible. They let you add HTML and dynamic components as discussed.
Platforms
My understanding of the marketplace is that nearly every programming platform has their own solution. For example, Python has Sphinx, React has Docusaurus, Vue has Vitepress, Go has Hugo, Ruby has Jekyll. There are some closed source ones, some enterprise-looking ones, and some basic ones that are all pretty capable. Even this blog, using Eleventy, turns markdown into pages with hardly any work (it's JavaScript).
Personally I use Vitepress for everything.
It'a admittedly simple to roll your own. Use a library to transform markdown into HTML. Use a library to surround your content with a layout. The simplest version of this is two steps. Just one if you vibecode it. There are enough edge cases and icebergs, however, that it makes sense to use an established tool.
HTML vs Markdown vs Other
While plain HTML is still a simple language and platform to write in, we tend to use the even-simpler Markdown language.
There are numerous others. Aforementioned Sphinx has ReStructuredText files. There's AsciiDoc. I suppose we could consider LaTeX. All of these are much more complex.
Markdown is about as simple as it gets. That's especially true considering it's a language on top of HTML!
There a downside that every page looks like wall-to-wall text (👀 umm 🫣 - yeah I'm writing this in Markdown here). The counterpoint is that you can interject HTML anywhere in most markdown engines to do things that are generally impossible in Markdown, like change text colors.
Summary
Your application needs a wiki, which acts as the team's homepage to the product. The best version of a wiki is a Documentation-As-Code platform.