Maybe Our Documentation ''Best Practices'' Aren't Really Best Practices

DZone 's Guide to

Maybe Our Documentation ''Best Practices'' Aren't Really Best Practices

So-called best practices may not always make sense in the wild.

· Writers' Zone ·
Free Resource

Kayce Basques, an awesome tech writer on our team, wrote up a pretty amazing article about his experiences measuring how well existing documentation best practices work for explaining technical material. "Best practices," in this sense, can be well-known industry standards for technical writing, or they could refer to your own company's writing style guide.

Recently I discovered that a supposed documentation “best practice” may not actually stand up to scrutiny when measured in the wild. I’m now on a mission to get a “was this page helpful?” feedback widget on every documentation page on the web. It’s not the end-all be-all solution, but it’s a start toward a more rigorous understanding of what actually makes our docs more helpful.

Read full post.

While I am not a tech writer, my role involves a huge amount of engagement with our tech writing team as well as publishing a lot of "best practices" for developers myself. I was amazed by how much depth and research Kayce has done on the art of writing modern docs through the lens of our team's content. I fully encourage you to read Kayce's article in-depth — I learned a lot. Thank you Kayce!

best practices, documentation, tech writing, writers zone

Published at DZone with permission of Paul Kinlan , DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}