The Art of Bad Technical Documentation: Explained by a Technical Author to a Manager

Dear Manager,

As the dedicated technical author, let me take you through the “Art of Bad Technical Documentation.” Buckle up because we’re exploring the pitfalls and perils of wrong documentation. Here’s why your documentation is ineffective:

Embrace Ambiguity: The Clarity Conundrum

Why be clear when you can be vague? Inadequate documentation thrives on ambiguity. Instead of providing specific instructions, opt for terms like “thingamajig” and “whatchamacallit.” This keeps users guessing and adds an element of mystery to their experience. Remember, a little confusion goes a long way!

Skimp on Details: The Sparse Symphony

Who needs comprehensive information? Give users enough to make them think they understand, but more is required to accomplish their task. Skip critical steps and assume everyone knows what you mean. For instance, “Attach Part A to Part B” works perfectly without mentioning the dozen screws and the exact alignment required. Less is more!

Organise Chaotically: The Disarray Dance

Create a comprehensive setup guide with troubleshooting tips, installation instructions, and advanced features. This will ensure users spend more time searching for information than using the product. Plus, it will turn your documentation into a treasure hunt—fun—fun, right?

Prioritise accuracy: The Error Extravaganza

Facts are boring. Spice things up with outdated or incorrect information. If a user follows the steps and things don’t work, it adds excitement. Who needs up-to-date screenshots or correct commands? Keep them on their toes and guessing!

Overwhelm with Jargon: The Terminology Tango

Fill your documentation with as much technical jargon as possible. If a user doesn’t have a Ph.D. in your field, that’s their problem. Avoid plain language and never define terms. This creates an elite club of those who “get it” and keeps the riffraff out.

Bore to Tears: The Monotony Marathon

Write your documentation like a legal contract—dense, dry, and devoid of any engaging elements. Forget about headers, bullet points, or visuals. Walls of text are your best friend. If your readers fall asleep halfway through, you know you’ve done a successful job.

Ignore Accessibility: The Inclusion Illusion

Accessibility? What’s that? Ensure your documentation is as unfriendly as possible to those with disabilities. Tiny fonts, poor contrast, and a lack of screen reader compatibility are essential. After all, catering to everyone’s needs is just too much work.

Conclusion: The Hallmarks of Bad Documentation

In summary, inadequate technical documentation is an art form that requires a special touch. By embracing ambiguity, skimping on details, organising logically, prioritising curacy, overloading with jargon, boring your audience, and ignoring accessibility, you, too, can create user guides that are as entertaining as they are frustrating.

So, let’s raise a glass to the fine art of lousy documentation. Here’s to keeping our users on their toes and ensuring our tech support team never runs out of work.

Scene: A Discussion Between a Technical Author and a Manager

But have you recently checked the Helpdesk call stats?

How often have you considered the conversation you want with a manager without respect for the written word? When you do, will it go something like the content below? So, let’s read A Discussion Between a Technical Author and a Manager.

Characters:

      • Technical Author (TA)
      • Manager (M)

Setting: A corporate office in the manager’s office. The room has a large desk, a computer, and bookshelves filled with documentation manuals.

TA: (looking concerned) I’ve been reviewing our latest product documentation and must say it could be better. Numerous inaccuracies make it hard to follow and lack coherence. Our customers have been quite vocal about these issues.

M: (dismissively) I think you’re overreacting. Our documentation is excellent, and customers always find something to complain about.

TA: (patiently) But the complaints are consistent. They mention the same problems: unclear instructions, lack of coordination between sections, and poor flow. These are not just one-off comments; it’s a trend.

M: (irritated) Our customers don’t understand the product. They’re not exactly the brightest, you know. If they can’t follow simple instructions, that’s on them, not us.

TA: (firmly) I beg to differ. Our job is to make the documentation clear and accessible. If multiple customers are struggling, we need to address that with urgency. Documentation is crucial for customer satisfaction and retention.

M: (defensive) We’ve been doing it this way for years. We can’t change everything. Besides, rewriting everything would be a massive waste of time and resources.

TA: (calmly) Consider this: poor documentation already costs us time, money and resources. Also, our contract of delivery states we will supply up-to-date documentation. If a customer reads that, we could find ourselves up to our necks in a lawsuit for providing defective user guides. Another point: I read in a trade magazine our software ranks number 10 out of fifteen competitors, and our company is haemorrhaging cash. I also know you have contracted three more help desk pros to help with the increased demand for the increasing number of calls. But have you checked the Helpdesk call stats lately? They are still overwhelmed with more calls and emails that we could avoid with better documentation. The other day, they were fielding One call every ten minutes, and many calls were from the same customers becasue our help desk needed to know the answer. With every iteration of our software with more add-ins, our customers need help finding solutions that our software promises to fix. And our frustrated customers are turning to our competitors. Better documentation will help the support team. It works two ways.

M: (reluctant) So, what do you propose?

TA: Let’s start by conducting a thorough review of the documentation. I’ll work closely with the product team to ensure we capture all the details accurately. We can reorganize the content to improve the flow and clarity. We should also get feedback from some loyal customers before finalizing anything.

M: (sceptical) And you think that will make a difference?

TA: (confidently) Absolutely. Clear and well-structured documentation can significantly enhance the user experience. It reduces the need for support, increases customer satisfaction, and leads to better retention and word-of-mouth.

M: (sighs) Alright, fine. Let’s give it a shot. But I’m holding you responsible for this. If it doesn’t work, it’s on you.

TA: (smiling) Fair enough. I’ll get started right away.

M: (grudgingly) Make sure it’s worth it.

TA: (determined) It will be. You’ll see.

Narrator: The technical author embarked on a mission to overhaul the documentation. The technical author transformed the documentation into a clear, comprehensive, user-friendly guide through meticulous effort and collaboration. Customer complaints dwindled, support requests decreased, and satisfaction soared. Despite resistance, the manager couldn’t deny the positive impact of the improved documentation. The technical author had indeed saved the day.

How to Win Over Management and SMEs: A Hilarious Guide for Technical Authors

So, you’ve embarked on the noble quest of a technical author. Your mission, should you accept it (and you have no choice), is to convert the mighty management and the enigmatic SMEs (Subject Matter Experts) to your way of thinking. Sounds like a Herculean task? Fear not! Here’s your humorous guide to charming them into submission while keeping your sanity intact. Remember, we’re all in this together, united by the common goal of effective communication. So how to Win Over Management and SMEs to your way of thinking.

Speak Their Language (No, Not Klingon)

Let’s be honest—management speaks in KPIs and ROI, while SMEs converse in an ancient dialect known only to a few. Your first step is to become a polyglot. Learn to weave your documentation magic into business objectives and arcane technical details. It’s like being a translator at the United Nations but with less chance of starting an international incident.

The Art of Presentation: Smoke and Mirrors

With communication, clarity icriticaley. But why stop there? Make your points with the flair of a Las Vegas magician. Use charts, graphs, and infographics that sparkle. And remember, nothing says “I know what I’m talking about” like a well-timed meme. Trust me; pie charts are irresistible to management as cat videos are to the internet. Please don’t overdo it, or you will end up in a meme yourself!

Quick Wins: The Fast and the Furious

Management loves results faster than a pizza delivery. And who’s the hero delivering those results? You, the technical author. Identify accessible opportunities and deliver those quick wins like Vin Diesel in a muscle car. A tiny tweak will save an hour of work each week or a new tool that doesn’t require a PhD. Shout about those victories with the enthusiasm of a game show host handing out prizes. You’re the star of this show.

Collaboration: Herding Cats, but With Treats

Getting management and SMEs to work together is like herding cats, but don’t worry—we have treats! Engage them early with workshops that are part of brainstorming and therapy sessions. Provide plenty of coffee and snacks; they’re more likely to engage if their blood sugar levels are stable. Plus, who argues over a cookie?

Build Relationships: Be the Office Barista

Relationships are everything. Become the office barista—always ready with a listening ear and coffee. Trust and rapport are your best friends. Remember, it’s harder to say no to someone who knows your coffee order by heart.

Highlight Long-term Benefits: The Crystal Ball Approach

Paint a picture of a future so bright they’ll need shades. Highlight how your approach will lead to fewer headaches, lower costs, and maybe even a tropical vacation (we can dream). Show them the long-term benefits with the enthusiasm of a late-night infomercial host. “But wait, there’s more! If you adopt this strategy now, you’ll also get…”

Embrace Technology: The Cool Kid in School

Introduce new tools and technologies like you’re showing off the latest gadget. Be the cool kid who knows all the shortcuts and secret features. Offer training sessions, but make them fun—think less “seminar” and more “techno party.” Bonus points if you can throw in a few tech-related jokes. “Why do programmers prefer dark mode? Because light attracts bugs!”

Example Scenarios:

      • Scenario 1: Management Concerned About Cost: “Dear Management, investing in this new tool is like buying a golden goose. It’s pricey upfront, but think of the endless eggs. In financial terms, that means reduced time, fewer errors, and overall productivity that will make our competitors weep.”
      • Scenario 2: SME Resistance to Change: “Dear SMEs, we know you love your ancient rituals, but imagine a world where documentation is a breeze. Join our workshop—there will be snacks!—and let’s create a workflow so smooth, you’ll forget what life was like before.”

Ultimately, winning over management and SMEs is about strategy, charm, and humour. So, arm yourself with these tips and spread the word about the importance of good documentation. Keep in mind that these strategies have been tried and tested. If all else fails, remember that bribery with baked goods is always an option. With these tools, success is inevitable.

How do you manage a knowledge base for a project in the development phase.

Managing a knowledge base for a project in development is not just a task, but a crucial step towards empowering every team member with time-saving information. So, how do you efficiently manage a knowledge base for a project in the development phase? Here are some steps to handle this:

  •  Centralised Knowledge Repository
        • Choose a platform: Select a platform that suits your team’s needs. Options include Confluence, Notion, SharePoint, or a well-organised GitHub repository.
        • Organise Information: Create a structured outline with categories, such as
          • project overview,
          • technical documentation,
          • meeting notes,
          • feature specifications, and
          • troubleshooting guides.
  • Documentation Standards
        • Define Standards: Establish documentation standards and templates to ensure consistency. Include guidelines for writing style, formatting, and required sections for each document type.
        • Regular Updates: update documentation to reflect the latest developments and changes in the project.
  • Version Control
        • Track Changes: Remember to use version control for technical specifications and code, using tools like Git or integrated features in platforms like Confluence. Version control enables you to track document changes throughout their lifecycle, making it easier to revert to a previous version if necessary. 
        • Change Logs: Maintain a change log to record significant updates or revisions to the documentation.
  • Access and Permissions
        • Set Permissions: Define who can view, edit, and manage different knowledge base sections to maintain control and prevent unauthorised changes. Do this through the platform’s settings or by assigning roles to team members.
        • Ease of Access: Ensure the knowledge base is easily accessible to all team members, with intuitive navigation and search functionality.
  • Collaboration and Feedback
        • Encourage Contributions: The knowledge base is not just a repository of information, but a collaborative space. It’s a place where every team member can contribute, fostering a sense of camaraderie and shared responsibility. Implement a review process to ensure the accuracy and quality of the contributions. 
        • Feedback Mechanism: allow team members to provide feedback on the documentation, suggesting improvements or reporting issues.
  • Training and Onboarding
        • Onboarding Materials: Create onboarding materials for new team members, including guides on how to use the knowledge base and where to find critical information.
        • Training Sessions: Conduct regular training sessions or workshops to ensure all team members know the knowledge base and its importance.
  • Integration with Development Tools
        • Tool Integration: Integrate the knowledge base with your development tools (e.g., Jira, Slack, Trello) to streamline workflows and ensure documentation is part of the development process.
        • Automation: Automation updates documentation based on project management tools or codebase changes.
  • Regular Audits and Maintenance
        • Periodic Reviews: Schedule regular audits of the knowledge base to ensure the information is still relevant and up-to-date and the accuracy and relevance of the information you rely on.
        • Clean Up: Remove outdated or redundant information to keep the knowledge base lean and valuable.