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

Кейси Баскес, замечательный технический писатель из нашей команды, написал довольно удивительную статью о своем опыте измерения того, насколько хорошо существующие рекомендации по работе с документацией работают для объяснения технического материала. Лучшие практики в этом смысле могут быть общеизвестными отраслевыми стандартами технического письма или руководством по стилю написания ваших собственных компаний. Проверьте это!

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.

Read full post .

Несмотря на то, что я не технический писатель, моя роль включает в себя огромное взаимодействие с нашей командой технических писателей, а также публикацию большого количества «лучших практик» для самих разработчиков. Я был поражен тем, как много Кейси провела исследование искусства написания современных документов через призму содержания наших команд. Я полностью призываю вас прочитать статью Кейси всесторонне - я многому научился. Спасибо, Кейси!

Paul Kinlan

Trying to make the web and developers better.

RSS Github Medium