To all my underappreciated hard-working
InfoDevs in the world, I dedicate this
dead man’s chest of doc cases.
And a bottle of rum. Harr!
‘No one ever reads documentation, why bother with it?’
Favorite opening line of any techie, heard every time when I introduce myself as an Information Developer. I hope I don’t burn in hell when I say that more often than not, I as an Information Developer agree.
Of course, pride, honor, and all things sacred don’t let me admit it. Just a polite smile, no hatchet… I mean, sure, I of all people know that docs are indeed useful. And sure enough, I’ve read of more than one case when the availability of docs made a huge difference. But that only leaves me wondering, why I never end up in such cases.
Having had my fair share of sailing in high seas, I must confess that to keep afloat, you need to join the right fleet. So, master of the docs, it’s time to choose your crew, and here’s a couple of pointers.
No to Royal Navy, a.k.a. massive enterprises and statutory systems
Welcome to the disciplined and polished crew of Commodore Norrington!
We all know of huge corporations that rose from the ground decades ago but never quite managed to keep up the pace with times and technologies. Or, corporations like banks and governments that have a huge ballast of guidelines and regulations and take forever to implement a tiniest change.
The software that goes with those kinds of companies is just as rusty and bulky. And that’s exactly where most Information Developers earn our daily bread. Because in cases like these, a quick choice needs to be made. An eye patch to cover up the problem, instead of eye surgery to fix it. And it’s alright, except that these temporary fixes tend to stick permanently.
Providing the users with a document is quicker than redevelopment. Definitely cheaper. Everyone’s happy. Except for the users. Because there’s no easy way to document complicated software. Now, the users have to struggle not only through the complex software, but also through a multi-page guide. It’s helpful, true, but it doesn’t change the big sad picture.
Also, legacy software often comes along with legacy people, so you with your context-sensitive help systems will probably be taken for a young punk raising mutiny with some new age nonsense.
Anyways, in case of Royal Navy, start on it, learn on it, but don’t drop your anchor there for long. They sound like they’ve got big cannons but they’re slow at aiming. By the time your ground-breaking ideas and process improvements get implemented, you’ll be lost and forgotten in the bellows of the million-people corporation.
No to Hector Barbossa, a.k.a. thrifty legacy products
Now, there are many companies that get lured by shiny horizons of cheap development. And quite suddenly, you’re stuck writing a guide where every second sentence begins with ‘in case you…’. Talk about exceptions outnumbering the rules, eh?
If there’s one thing I learned on my job is that little gets you down more than cleaning up someone’s UI mess. Like, when you have to document a non-intuitive dependency between some fields. Or, when an error message is ambiguous, and you have to chew it over in the doc… Easy dev fix, message rewording, right? We’ll implement it within this sprint, right? Yeah, right…
Well, mate, dig your pirate heels in. There’s a leak in the ship, and you’re kept bailing the water out with a tiny flower bucket. Keep sounding the bell about the need to actually mend the leak instead of fighting the consequences. Because no one reads the damn docs – that’s probably like your strongest argument there 🙂
And if the ship keeps leaking… think about it, would a smart pirate hedge his bets on the ship called ‘Dying Gull’? Well, neither should you. Better walk the plank earlier than sink later, savvy?
Yes to Elizabeth Swann, a.k.a. modern crafty solutions
The cases above were all about good ol’ well-established institutions. Now, about the lean and mean young blood in the game.
Most modern products, be they websites or desktop apps, for ecommerce or gaming, have been built with people in mind and made useful in their basics. Hence, clear workflows, progressive disclosure, appealing design – what else is there to wish for?
A classic manual in this case would be 80% about obvious how-tos and 20% about interesting what-ifs. There’s a way though for you to turn those numbers around: focus on the business context, general workflows, and pro tips for using the product to its biggest potential.
Here, documentation is not so much about guidance, but rather a welcoming touch, a show of support, and an offer to shake hands with the users.
Companies that are out for profit need to remain quick, maneuverable, and open to change, prepared to adjust to everchanging currents. Here, you have space for creativity and innovations, and a greater chance to gain professional satisfaction and recognition.
Yes to William Turner, a.k.a. complex state-of-the-art solutions
Now, what about the octopuses of the software world, the programs that are reasonably usable but at the same time deeply specialized and made to handle multiple variables? Like, have you seen software for controlling music show equipment, or systems for forecasting the risk of natural catastrophes? Usage guidelines for them are a real treasure map.
Fixing up instructions for such software requires a lot of skill, practice, and determination to deliver what is right for that specific audience. The more effort and passion you put into investigating documentation use cases and stakeholders, the likelier you are to author genuine, sometimes even revolutionizing deliverables.
Still, the winds of technological fortune are blowing away from huge bulky all-in-one systems towards suites of small solutions that are easy-to-use and aimed at resolving one business need each. These solutions are then well-integrated with each other to ensure an undisrupted business process in its entirety.
All you may need here is basically a two-pager explaining the data flows and the overall start-to-end process. As for in-depth usage details, smart solutions are made for smart guys. Let them figure out the software by themselves. If they’re looking for documentation, it’s probably case studies and corner-case tutorials from other master users filmed with a shady webcam and fuzzy voiceover.
Yes to Jack Sparrow, a.k.a. startup solutions
Now, here come the guys who explore the unknown waters. Innovators. Startups. Modern thinkers. Black Pearls of all ships. Sea hounds who sniff out terra incognita and fill a softwareless niche in a way that you cannot understand how you lived without their app before.
That’s adventure you’re lucky to be in …and as easy to find as a sober pirate. But if you do find it, you’re one lucky Jack. And just like our favorite pirate, you’ve got to always be at your best.
Products like these, well, they settle only for a perfect match. Your docs got to be close at hand. Relevant. Sleek. Alluring. Suggestive.
Still, funny thing is, delivering nicely layouted, well-written, and standards-compliant docs is just a start, just like getting a ship rigged. The actual work begins when you put that rigging to use. In case of docs, it’s about keeping them accessible, usable, convenient, and well-maintained.
This kind of work is challenging, but at the same time rewarding. Get your compass tuned for success and seek out opportunities like this, because your docs will remain used and fresh in the game, no fountain of youth needed.
That’s that! Hope this article was useful and entertaining. This is by no means a one-pirate show, so submit your ideas and questions to our crew!
Ahoy, good sailor, what ship are you on now? If you’re willing to set sail with us, well, you can find ELEKS InfoDev pirate vacancies right here. All aboard, and on to the raging seas together 🙂