So the documentation wiki at our work is broken. Well it’s actually works just fine, but it’s neglected and unloved. People write documentation for various reasons, things change, and nobody updates the documentation (either they forgot, or the people making the changes didn’t even know it existed). For us, we have a lot of documentation that hasn’t been touched for years. No-one is sure what’s still relevant. So there is talk about moving docs from the wiki to our GitHub. While not a bad idea in itself, it seems to solve none of this problem of neglected documentation.
So what’s the answer? Do we need more discipline? Should we make documentation a first-class citizen the same way we treat tests?
I want you to consider a really contrived example:
class Foo {
public int add(int left, int right); // implementation is left as an excercise for the user
}
Suspend your disbelief some more and pretend this thing had documentation (I’m pretending this is what documentation even looks like)
## Class Foo
### add(int,int) -> int
Adds two numbers
Here’s my idea: So what if the documentation instead looked like this:
## Class Foo
### add(int,int) -> int
<!-- assertion: foo.lib Foo.add 931606baaa7a2b4ef61198406f8fc3f4 -->
Adds two numbers
In other words, I had a tool that could:
- calculate the hash of a function
- validate that Foo.add in foo.lib matches the expected assertion
So the idea being that, if Foo.add ever changes the hash would change and the documentation will be invalid. Now this isn’t great of course, because improvements to the function (ie. bounds checking) would cause a whole bunch of assertions to fail. Not ideal. So what if we tied it to tests? Of course this thing would have tests
[Test]
public Add_TwoNumbers_ReturnsResults() {
int results = m_foo.add(1,2)
Assert.AreEqual(3, results);
}
## Class Foo
### add(int,int) -> int
<!-- assertion: footests.lib SomeClass.Add_TwoNumbers_ReturnsResults 557c0271e30cf474e0f46f93721fd1ba -->
Adds two numbers
Bounds checking would be a different test, so the hash wouldn’t change.
It’s an idea. I don’t have a working concept yet. There are also many pitfalls to this approach. Refactoring code might introduce a bunch of failures. Not everything can be captured in code, such as architecture diagrams. Maybe an interesting weekend project over the Christmas break.