Having seen it pop up on job listings a lot recently, I thought there might be a good opportunity to go over the dicey subject of documentation. A frequent bane to developers and product owners alike, the habit of forming clear and concise documentation best practices is one we should all get into, whether we enjoy it or not.
Why Document?
Much has been written on the importance of documentation to businesses. It’s an area that affects many sectors, and at its heart, addresses four key competencies, and three focuses.
Competencies
1) Team Integration
One of the core beliefs common to multiple team and business methodologies is that of a shared vision. Be it working toward a value proposition, or day to day maintenance, the cohesion of a team often defines its effectiveness. Documentation can ensure that project vision is contiguous throughout the organisation.
2) Training and Standardisation
Linked to project vision, the process of onboarding can be a major cost and time investment for an up-and-coming business. Good documentation not only reduces this overhead through the streamlining and standardisation of processes but ensures that diverse workflows and multi-disciplinary teams can gel throughout the nascent structure that’s being built.
3) Money, Money, Money
Let’s be real, the point of business is to maximise value to stakeholders. The efficiency and effectiveness of a project are closely linked to the time requirements for processing. These can be minimised through a good knowledge management system that enables stakeholders to access what task-specific information they require as readily as possible.
4) Professionalism
Documentation isn’t just an internal metric. Often-times project documentation forms the first line of contact for product users when they hit your site or require help with your project. Good documentation forms a good impression of your organisation and can, in the best practices, reduce the burden on your support staff.
Focuses
To get a bit more technology-specific for a second, both internal and external documentation amongst information-lead organisations often hones in on three core areas:
1) Development
That is to say enabling future development, and reinforcing the current. Both AGILE and ITIL workflows require a starting point of knowing “where you are now” before you pick your heading, and documentation forms a key part of this. Similarly, triage efforts for limited resources require an accurate set of metrics for understanding the current workings of your projects from a multi-factored basis.
2) Maintenance
This one really should be fairly straight forward to anyone who’s tried to keep anything maintained, from a Minecraft server upward, but knowing what’s there, what you’ve done, and often what’s already gone wrong, is a crucial part of knowing what to fix. No one enjoys combing through a hundred lines of logs just to solve a problem you’re gleefully informed was already spotted last week. Let alone that developers are (generally) human, and capable of forgetting things.
3) Knowledge Transfer
Your team may not be with you for the life-cycle of your product. Your host or provider or subcontractors may need to be changed as the market changes around you. There will be times where the quick and direct transfer of information relating to your products and deliverables is a pressing necessity for your business. That is the last time you want to find something missing.
So that’s the business spiel we all know and… tolerate… so what about the you? Why have I not centred the human?
From the Business to the Personal
So let’s do that instead. You’re sitting down to get something done, a personal project, a favour for a friend, or just a way of whiling away our vast tracts of Covid filled time: I’d make the case that documenting your own personal work is helpful for much the same reasons as were laid out in the business metric. For a start, it makes coming back to things after a break easier.
Whether you’re distracted by your pets or children or the sudden appearance of something shiny in the room, the sinking feeling of returning to a project after a few days only to not have a clue where you were with it is one I’m sure we’re all familiar with. Keeping a project journal or documenting-as-you-go can help with this.
If you’re a bit colder and ruthlessly pragmatic, documentation is a great way of impressing upon potential employers that you’re keeping yourself up-to-date in your general life.
Whatever your motivations, once you’ve settled on your aim and steeled yourself to do the dreaded writing thing, one question remains. How do you get started?
For most people, some type and degree of planning is required.
Now, I’m more than aware that the approaches to self-organisation are as diverse as the people attempting things, and I’m not about to grab my soapbox and try converting anyone. However, to borrow a much-loved shibboleth from the world of creative writing, people tend toward being “pantsers or planners”, also known as “gardeners or architects”.
So what does this mean?
Simply put it’s a general split of people who take a prospective or a retrospective approach to creative pursuits. To me, at least, problem-solving fits under this banner. Be it writing a story, painting a picture, or solving a technical problem; there’ll be a process flow that comes most naturally to you.
Prospectives
The “architects and planners” of the dualism. You’re one of those people who like to sit down and plan out your approach and stepwise action plan for the coming task. In some ways, this will make your documentation easier. After all, if you’ve sat down, maybe with your Kanban board (more on that later) or maybe with your notepad, and started to plan out what comes next, that can directly inform the structure and direction of the eventual document.
However, you can’t get complacent. There are some pitfalls to a ‘plan first’ approach.
Theoretical Weight-Lifting
To borrow a term from historian and journalist Oliver Bateman, don’t get trapped in the void of ‘theoretical weight-lifting’. Many will be familiar with the so-called “research black holes” that form when you dedicate too much time to the artifice of planning your project rather than actually doing it.
For writers, this can be world-building without story-crafting. For artists, this might be finding the perfect materials and references without ever putting brush to canvas. For technologists, this could be planning ever more elaborate system architectures whilst you slowly lose track of which problem the product owner actually wanted to be solved.
Keep it firmly in mind during your planning phase that no matter how much of an expert you might become in the theoreticals of your project sooner or later you’ll have to, as Oliver notes, “…pick up the fucking weight.”
Flexibility and Fate
So you’ve got your plan. Great plan, on paper your road stretches ahead, lined with gold to the end of the proverbial rainbow.
But then you start walking.
Inevitably, something will go wrong. “No plan survives first contact with the enemy,” and all that. It’s very easy to sink large amounts of time into an overall insignificant step that just isn’t going how you want it.
Don’t.
Take a step back. Keep your plan flexible. Step around or bypass or just pick a different approach. Plans can be rewritten. Documentation can be updated. But at the end of the day, the product needs completion, and you probably have a deadline to work to. Just because a plan was written, doesn’t mean those events are fated.
Retrospectives
The “gardeners and pantsers”. Get stuck in and ask questions later. You don’t have time for this documentation nonsense until you’ve got the problem solved. You want to write your story then check for consistency when you hit first edits.
That’s fine.
But make sure you hit first edits.
Attacking the meat of the problem first, wanting to get on with “doing the work” is great, but it doesn’t actually mean that there’s no planning or documenting involved. Undoubtedly you will have methodologies in mind whilst approaching the obstacles in your way, and noting them down can be of great help when you end up revisiting the same issues later.
Putting those notes in your code. Leaving yourself little editing tips, or tags that say “come back to this later” is going to be vital for your work to be understood by others and reach the level of completion that you envisaged at the start.
‘Mise-en-place’ and ‘Clean-as-you-cook’
So you’re cooking your meal, and you’re using your equipment — in this perplexing culinary metaphor that has intruded from nowhere — but you’re in the “ideas space” of the kitchen, and at some point, someone else is going to have to use it, or at least ask you for the recipe. That was torturous.
But I’m basically suggesting you should remember to do the washing-up.
I’ve not yet seen someone solve coding problems without scribbling any notes at all. I’ve never seen a writer whose first draft required no editing.
Whether you use a whiteboard, or a little notebook that you overwrite in the corners and margins, you’re going to have had to jot something down whilst you engage with whichever problem you faced during the project. When you got to the end of that struggle, when the code finally stopped returning errors, you got a hit of dopamine.
That’s the point you should tidy things up.
Write down what the finished solution involved. Tidy up the notes you made so that you can actually understand them, even if no one else can. When you return to this problem in five months time because you’re pretty sure the solution is relevant again, you want to be able to understand what you were thinking.
You might not have set up all the ingredients beforehand, but you should make sure that you at least know what they are and how you used them by the end.
Toolsets and Methodologies
So you’re out of the office, you’re back home, and you may not have access to all of the tools you’re used to. Maybe you’re trying a new thing. Maybe you’re sadly no longer employed. I’m going to take the time to run over a few free resources that can help you set up well structured and accessible documentation.
These are not the be-all and end-all. There may well be more powerful or broader tools out there. These are just a few free and largely browser-based examples to help you on your way.
Trello
Trello offers a free, board-based planning system that allows for KanBan and Scrum style workflows and integrates with Butler. It features sync across multiple devices, the creation of public or private boards, and is particularly useful for cooperating with teams at a distance.
From an aesthetic perspective, the custom background images and colour options work well for those who prefer visual aids. Having worked on a project that involved MoSCoW task triaging, the traffic light system we set up was a useful reminder during daily standups. More recent Butler integration enables automation of tasks on trigger, rule, or time bases.
Atlassian’s Jira fulfils the same niche, as well as being broader in both scope and integration. However, its free version has limits on team-size and functionality. As it is more commonly used in professional environments I would urge some familiarity with its workings, though I leave it entirely up to you as to its necessity for personal projects.
SimpleMDE
SimpleMDE is a basic markdown editor built on javascript and accessible through a browser. Though markdown can technically be written in any text editor, SimpleMDE’s clean layout and AI-driven adaptive trimmings can be a boon for writing hassle-free READMEs.
GitHub
GitHub is perhaps the place to host code. Whilst I’m sure everyone is familiar with its basic functionalities, and certainly, anyone who’s set up a repository will be intimately familiar with the necessity for a README.md, they may not know that GitHub has its own guide to setting up documentation and the facility to directly host wikis that interface with project directories.
LucidChart
LucidChart is an online chart maker specifically focussed on software diagramming. Certain aspects of code design, particularly when related to demonstrating architecture or business flow, are far easier to follow in a visual medium than through volume upon volume of written description.
That’s where LucidChart comes in. I’ve found its free offering to be sufficient to churn out architectural and flow diagrams for a few of the projects I’ve been involved with. It should be noted, however, that not all features are available in the free versions, and there is a limit on the number of projects you can have available for editing at any one time.
Paid accounts are available for the site, and discounts provided to students.
Doxygen
Doxygen automates a large portion of the process of documentation, either in HTML or LATEX format. Of the free automated documenting programs I have seen, it offers the largest support for languages, boasting compatibility with “C++, C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavours), Fortran, VHDL and to some extent D”.
Perhaps its most appealing function is in allowing fast access to undocumented code bases so that you can quickly reorient or integrate yourself with challenging research projects.
Grammarly
Grammarly, as the name might suggest, is a tool for checking the spelling and grammar of writing. It comes in site, plugin, and app varieties, and integrates well with most websites, including Google Docs. I’ve found it most useful as an advisor rather than dictator, and I strongly recommend having enough of a background in grammar and style guides to judge whether its suggestions are appropriate for the situation.
It also currently only supports the English language, though it does differentiate between British English, American English, and Canadian dialects and spellings. Whilst planning and coding tools are all well and good, having the eventual documentation comprehensible to others is an unfortunate requirement of written communication.
But what about methodologies?
I’m tempted to say, “Yeah, what about them,” but that would be overly facetious. Organisational business planning is a broad field, and in most cases, the requirements for such will be set by your employer. If you wish to learn a broad overview that may spark some insights into how to better plan your own work, you could do worse than start here.
Time, Money, and Motivation
I believe, even in this year of all years, that the twin evils of motivation and availability can be some of our biggest obstacles to personal project completions. Getting up the consistent energy to continue with your own pursuits under the drudgery of boredom and stress combined can be a real challenge to anyone.
I’m afraid to say, fully tackling this issue would be a long way outside of the remit of this article. But I would like to explore a few of the intersections between documentation, planning, and motivation.
Time, Money, and Evil
Much has been said on the evils of both of these, but the simple necessity of needing to feel rewarded for our investments is likely as old as humanity itself. Calculating a reward pathway for the effort expended for individual projects can be a key way to continue interest and motivation, particularly in a time which has seen both the gig-economy and grey economies exploding due to the particular constraints of lockdown.
The accumulation of experience for its own sake may well be essential for an Aristotelian pursuit of eudaimonia, but it’s a somewhat utopian project in the cut-throat and fast-paced world of modern living.
Monetising either your approach to, or your end goal of, a particular pursuit can go a long way to keep you focused on a task. I’m going to cover some of the more digitised aspects of the gig and temp economy, as well as freelancing opportunities in a future article, but for the time being: start small.
Can you post your results somewhere that gets your name out there?
Would your coding efforts be instructive if blogged about? Could your creative writing be sold to a lit-mag or given over to a youtube narrator? Would your Inktober offerings land you an illustrator role if you posted them on more than just Instagram?
Can you find a community that offers you feedback?
Operating in a vacuum, practising what might as well be some form of intellectual incest — where your own ideas reproduce only with your own ideas, never interfacing with the greater world — will make it very difficult to improve on your chosen path. This is something that documentation greatly helps. Once you’ve got a project in a state where you can not only demonstrate it but clearly explain it to someone, then it’s time to:
Get feedback. Evolve. Progress.
Knowledge Base Maintenance
Nothing lasts forever. A fact we all have to come to terms with, but it’s doubly true for skills and memories. The past is a fluid thing, our perceptions of it waning and warping as we move on from where we are. As the Nintendo Wii told us long ago:
Everything not saved will be lost.
Somewhat recently, a friend of mine — who was working on his 8th or 9th book — got to the end of the editing process and was preparing to format the novel ready for Amazon publication. To put it bluntly, chaos ensued.
Despite having done this process however many times, the many-month delays between each execution and quite possibly the stress of looming deadline had driven the information clean out of his head. This would not have happened if he had the notes from last time.
Poor Lex, to have been brought up as an example. But I believe it’s an illustrative one. He’s a deeply competent and driven person, performing a task he’s executed multiple times before. Yet, just before a major deadline, it cost valuable time and no end of stress to re-solve a problem with an already extant solution.
You can catch some of Lex’s non-professional writing here.
We lead long and complex lives, and good documentation of those things we’ve found useful to us, and those projects which might bear a second look, is a great way of making your future a less stressful place. By itself, knowing where to find information solves a lot of the trepidation you might feel toward starting something.
Keep your path to motivation as clean and simple as possible.
Storied and Historied
Boy, that’s been a trip. As we reach the end of this, the first in what I hope to be a series on documentation and work-practices in various contexts, I wanted to take the opportunity to tie together a few of the looser themes of the piece.
The first strands of thought that would become business management theories can be found in Frederick Taylor’s “Theories of Scientific Management” in the late 1800s. Questioned first by Elton Mayo in the 1930s, and then again by a range of psychologists and businessmen throughout the 20th Century, the practice shifted to ever more human-driven and systemic approaches. Arguably overhauled once more at the beginning of the 21st Century by the practices of Business Process Management, it has coalesced into the vast network of the industry we see today.
Insofar as modern approaches to documentation form a part of those frameworks of knowledge, perhaps it really does start there. But I’d contend we’ve been telling each other stories about our works for a lot longer, potentially for as long as we’ve had stories.
And that’s really, to me, a strong part of effective documentation.
Whether you’re providing installation instructions, or a company background, a team approach, or an apparently dry set of product specifications, there’s a story you wish to convey to your audience. Knowledge transfer in this way can be far more personalised and efficacious than otherwise.
You wouldn’t write your internal documentation the same way you’d write customer-facing documents. You wouldn’t write personal notes the same way you’d write a showcase for a prospective employer.
Oftentimes these things go unsaid.
And yet there’s so much to say about them. The audience forms a core part of the duality of writing, and it can be far too easy to forget, or at least not think about fully.
Join me next time for a deeper look at writing for an audience, and what you as an individual project author can learn from diverse approaches to communication.
Thank you for reading.
