Skip to content

The ClearDocs Manifesto

As a technical writer, I have observed that most developer documentation isn't at par with readability. I don't blame them since they aren't writing for the end user, instead their job is to distill the infomration in a manner that helps them or their peers understand.

That is where technical documentation comes into play. A writer's role is to translate that language into non vauge, non verbose and readable format. So if you're a SaaS business and you want the customer to adopt your product, good docs (aren't optional) but serve as the difference between adoption and abandonment.

ClearDocs Stands For

  • Content in plain and unambiguous language
  • Docs in sync with reality meaning accuracy
  • Information that has a logical structure or flow
  • Writing for the reader i.e. empathy first

The Common Failures of Documentation

  • Wall of Text

    Often we see the documentation is a long wall of text. I mean just because it is documentation doesn't mean it can't follow the "waterfall" structure. We should split content into paragraphs of 3-4 lines which keeps the infomration condensed.

    Makes it easier for the reader to consume and absorb the idea and move on to the next. Also, it is essential, a certain portion of the information or idea is captured in a paragraph making it meaningful. More than couple of ideas not fully fleshed out confuses the reader.

    ClearDocs avoids that

  • Code Dumps

    Documentation riddled with code dumps without explanation. Even if your audience is learned, they may not understand what block of code goes where. Ideally, it should explain why this line of code is added here and in what case the reader have to use it.

    The content should have proper spacing, preferably use of code blocks to differentiate code from text. In structured authoring tools like Paligo, we have program listing to initiate code blocks or areas that need to stand out for readability.

  • Jargons & Assumptions

    If the documentation is aimed for all users, we should not use the industry jargons or company specific assumptions. There are all sorts of users inlcuding privileged and non privileged users. An organization admin may interpret them correctly, but an operation-level employee or an executive will have a hard time getting around it.

    Yet we see, like random code dumps, documentation littered with inside jargons. Sure, customer using your software ought to know, but what if they don't? We shouldn't assume and thus, should stick with widely accepted terms or familiar words.

  • Outdated Information

    This is my biggest gripe with online documentation and user manuals. Dude, the UI changed and your screenshots are old, or that the path to access an item has moved and your docs still talk about the menu from the previous product design.

    With UX revamps rampant everywhere, instructional designers and tech writers should work closely with each other to communicate the latest changes to the customer via documentation.