When I was but a young fresh graduate rolling into the world of development and programming at a scale-out I’d joined, the best way I could learn new technology was going to base my super-awesome tech solutions on, was to download the comprehensive documentation that came with that technology, consume it (or at least parts of it) and then get hands on building.
My main issue with this was the sheer size of the documentation in some cases. Software installation could be cumbersome a few years back (and often still can be - OpenStack anyone? And who just said Kubernetes?) - there were pages dedicated to the art of installation alone - never mind doing something useful with the technology after that.
There was separate documentation for every hardware and platform combination the technology was supported on. Oracle RDBMS was a prime example of this and I spent many an hour finding and downloading the right documentation, reading and implementing. Everything felt so slow.
But here’s the thing - the documentation was generally really good.
Most of the time I wouldn’t have to go anywhere else other than the manual I’d downloaded to get stuff done. The time spent pouring over the documentation, sucking up the pre-reqs and how to install them, the point and click style instructions to install, walking through the basics of setup and admin, coding something new - all of it was worth it as I knew I’d be able to get what I wanted done just from one document or two.
Times have changed.
Today, we’re faced with a different type of documentation. The ‘just enough’ type. Which very often, is more the 'isn’t enough’ type. The documentation now often comes simply in the form of markdown in the README of git repos, or as a couple of paragraphs on some cool front of a web page. Possibly a quick blog post. Maybe in a message channel somewhere. Those millions of little ‘i’ information icons you get on pages with hover-over content? Ugh.
This documentation tells you that installing the software is as simple as yum-ing / npm-ing / brew-ing / curl-ing your way to development freedom. It doesn’t tell you exactly what happens under the covers and usually not how to tweak and change configuration for the optimal deployment you might want for your development or solution, or even what is available for you to tweak. It lets you ‘explore’ the software, without actually giving me best practices. It’s annoying.
When things go wrong (which at some point they always do and which no doubt is down to a good dollop of user incompetence on my part), I’m inevitably left searching google / stackoverflow / third party forum search to understand how long they wasted on getting what I wanted to achieve actually done.
The time this all takes equates to the same time it would have taken me to consume proper documentation in the first place and understood what it was I was installing and how best I can configure it for my use - but way less annoying.
I think the change in documentation could be down not only to the evolution of the tools we now use of course (like git, blogs, chat apps), but methodologies like agile that many a company are obviously embracing. I’m a big fan of the DevOps movement and of agile development. I come from that start-up / scale-out background where it’s the ‘standard mode of operation’, but very often documentation is sacrificed for development speed to the point where documentation isn’t good enough, sadly.
I’d love to see technical authors as part of the agile process, in scrum meets, adding to Kanban boards and so forth…an integral part of the development team. It really would help developers think about what they are doing and how it hangs together, validating what they are doing is actually being done for good reason. I’ve sat with many a technical author over the years and had moments where the author would turn around and ask why I was doing something a certain way and I couldn’t answer - I suddenly understood an interface I was developing or a widget I’d created was totally wrong for the purpose on not appropriate for the application, but had my head down for too long to call it out myself. I find producing a good level of documentation really helps my own development quality and the relevance of my output, overall.
Another impact of quality documentation is community development. A lot of software and developer focussed tooling is built in a community open source model these days. Far more than even in the recent past. I think communities are great at building modular code but pay less attention to the documentation to go with that code. There are so many moving parts to consider and to keep updated with a virtual team that could range into the hundreds. Again though, if we had folk more dedicated to the task of developing user documentation I think the pull-through adoption of software users to the open source software would easily justify the effort in the medium term, as it reduces the barrier for non-community folks to pick it up quickly. Let’s face it, the minute something doesn’t go well with a tool, like say, installing it or trying to do something basic with it, 50% of the time we’ll immediately walk away from it. That’s something we could really cut down.
At the very least, dragging someone off the street to install and use your development software / tool, from a cold start, would be hugely beneficial in a ton of cases to understand where your documentation fails, but more importantly where your software fails. It’s certainly worth putting more time and effort into the documentation of the software production process.
I don’t expect people to document a technology war and peace - and everyone knows the world could certainly do with less slides - but a little more effort on the developer documentation side would certainly make the software development world a better and more productive place. Or in my world at least - but I like to aim high.
Maybe I'm just an old Generation X'er now. Or maybe we need to pay more attention to documentation standards concerning our developer technology once again.
I’m pretty sure it’s both.
TBM.