Shed some light on your hard work – Tips to improve your documentation

Nothing is more frustrating to me as a computer programmer than trying to integrate with third-party software that is not documented well. I often say it’s like feeling around in the dark. Rather than clearly seeing how to accomplish my goals, I’m forced to feel around, trying many different things until I can finally come up with the results for which I set out.

On the other hand, when someone takes the time to document their product or process thoroughly, it makes life so much easier for everyone who uses it. I know it’s not fun. Not many people love documenting their work. But most people, if you ask them, want to help make the world a better place. Make someone’s day a little better by writing good documentation.

Here, I’ve outlined some tips to improve your documentation:

Add the Extra Details

What’s obvious to you isn’t always obvious to another. If your documentation starts to become too cluttered, consider using an appendix or including helpful links. Simply by adding a link, you’re saying, “It’s okay not to know what this is – go here to learn more,” making the documentation more inclusive and welcoming.

Keep it concise

Huge paragraphs and essay-like blocks of text are intimidating. Most readers will skim over them. Make it easier for the reader to see the important bits at a glance using these tactics:

  • Use two to three sentences per paragraph.
  • Include bullet points
  • Highlight important info with bold or italic formatting. For example, add strategic bolding in the first sentence of each paragraph and use regular font for the supporting details. (see what I did there?)

Use Screenshots

A picture is worth… a lot of words. Visual aids help clarify your documentation, making it easier to understand and apply.

Review and test for accuracy

To make sure your documentation is complete, recruit a colleague to review it. If they have questions or make mistakes, you’ll need to make some revisions.

Don’t just document well for others… do it for you! You’ll get fewer support requests or follow-up emails. Also, chances are that six months from now, after working on dozens of other things, you’ll forget why or how you did something, especially if it was a clever something.

Interested in learning more? Check out our website for a variety of informative legal technology blogs – https://adaptivesolutions.com/blog/

BE ALERTED WHEN WE ADD NEW BLOG POSTS!

17343

Subscribe to the ASI LegalTech Blog

WHAT ARE YOUR THOUGHTS?

1 Comment

  1. Michael Wachter on September 28, 2018 at 2:05 am

    Great stuff John! I found that using Jing snapshots with boxed carve-outs with and with messages helps to keep the text paragraphs more concise.

    Thanks again for the outline, really good guidance here!

    Michael

Leave a Comment





SHARE THIS BLOG POST!

BLOG POST WRITTEN BY
John fell in love with programming back in the years of AOL chatrooms and has been developing professionally since 2002, coding mostly in VB and VBA. Since joining Adaptive in 2008, he has gained experience with the WorkSite API, app development, and many other technologies. Outside of work, he enjoys spending time with family, being outdoors, running, and playing almost any sport.