Maybe Our Documentation “Best Practices” Aren”t Really Best Practices

This content originally appeared on Modern Web Development with Chrome and was authored by Paul Kinlan

<p>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 it could be your own companies writing style guide. Check it out!</p> <blockquote> <p>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 towards a more rigorous understanding of what actually makes our docs more helpful.</p> </blockquote> <p><a href="https://kayce.basqu.es/blog/best-practices">Read full post</a>.</p> <p>Whilst I am not a tech writer, my role involves a huge amount of engagement with our tech writing team as well as also 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 teams content. I fully encourage you to read Kayce's article in-depth - I learnt a lot. Thank you Kayce!</p>

This content originally appeared on Modern Web Development with Chrome and was authored by Paul Kinlan