On Documenting Software Engineering Projects

I started working through my own fork of the Open Eats recipe site software.  To date, I've only made a few minor changes, such as placing (almost) the entire repository in an openeats module, so that the manage.py file can run correctly without further user setup.  I've also started documenting a lot of what I'm finding here.

One of the first things I questioned was where my documentation should live.  I've essentially got access to this here blog, the above wiki, the issue tracker attached to Bitbucket, and the code itself.  I'm sure my preferences will change over time, but here are the current rules for documentation usage:

• Code - Documentation - much to the surprise of a younger version of myself - should be minimal here.  If the 'how' of the code is unclear, the code should be refactored.  If there's a specific 'why' behind an algorithmic design, that's fair game, though I could argue that documentation belongs in the wiki.  Architectural/project design should be left to the wiki.  So, the code should really only behave as an actor, not as an explainer.
• Issue Tracker - Document immediate issues that are either enhancements (which I'm also treating as stories) or bugs.  I'm not using any other types.  If they existed in this simple bug tracker, I'd potentially use epics to group bugs and enhancements, but they don't, so I won't.  Things here should be immediate calls to action with very specific exit criteria for fixing.  There may be some overlap with the wiki on information, but that's OK.  We don't refactor issues or wikis, so duplicate information is OK.  Although, we should be very diligent in editing the wiki to ensure that information is correct.  Issue tracking requires less diligent editing, as issues are expected to be ephemeral and out of date at some not too far distant point.  Of course, anyone who's ever managed a backlog knows this isn't always true, but the principle still holds.
• Wiki - This is the canonical documentation and requires the most care.  Wait, what!? Don't you mean the code requires the most care, since it runs the site?  Well, maybe.  In most cases, you'll be reading a lot more code than you'll be writing.  If you're not, even as part of greenfield development, you're doing it wrong, because you're copying and pasting from stackoverflow without understanding what's going on.  Second, the code is to some extent, self-correcting.  If you add a feature and it doesn't work correctly, you'll eventually find out.  If your documentation is wrong, you'll only wind up frustrating people in the long run who expect it to impart correct information.  The wiki can be used for just about anything, and I'd say that shading toward over-information is preferable to less information, as long as you're following along with a decent narrative (so, don't just barf up some documentation from somewhere else and expect that it will be sufficient for your wiki).  People are going to come to your wiki to understand just about everything, so you should give it the appropriate care.  What's more likely than not to show up in a wiki:
• Architectural overviews and decisions.
• Notes that are expected to last a long time and show why the decisions that are in place are in place.  
• Notes describing particularly inscrutable or idiomatic code choices.  This reduces the text volume overhead in the code itself.
• Discussions for future enhancements or extensive bug work.
• Blog - I've debated a bit about whether or not both a blog and a wiki are necessary for documentation in this case.  If I had to jettison one, I'd lose the blog, but I think that a blog does a good job of complementing the wiki.  A blog generally shades toward thought process, while the wiki shows the output of that thought (though a wiki can also show thought process).  A blog is good for discussing meta topics (like this one about choosing documentation standards).  A blog is time based, where a wiki is more generally a static snapshot.  So, I can write a lengthy post about documentation standards and then completely contradict myself next week without making edits to the wiki documentation.  If I were promoting the recipe website, a blog serves as another separate medium for marketing, which serves a useful purpose.  Finally, a blog allows me to go off-script with various posts (say, if I want to review Rogue One tomorrow) without seeming too out of place.

A few final notes on documentation - 

Given the comprehensive abilities of markdown files, I'm fine with the argument that a good README.md with children could supplant a traditional wiki.  In fact, now, as I write this, that may be a better option, as then the repository and documentation is entirely self contained.  For the moment, Bitbucket makes it easy enough to integrate issue tracking, code, and a wiki that the argument for markdown is a little academic.

The most important part of this post (talk about burying the lede), is that documentation is difficult.  It requires a lot of writing and editing.  It's extremely time intensive, and can be frustrating when you put in a lot of effort, but people either don't get your point or don't read it.  However, those aren't excuses not to document.  Code without documentation is essentially dead code.  Code is part of a living ecosystem and needs support - it never lives in isolation.

This holds more true in the commercial space than in the hobbyist space, but, even though you may know the code like the back of your hand, eventually you'll quit or move on to something else and someone will need to support what you've built.