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

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!