Перевод: 13 ошибок, которые допускают разработчики при составлении документации

Оригинал: 13 Things People Hate about Your Open Source Docs

Большинство разработчиков ПО с открытым исходным кодом в основном задумываются о качестве программ, которые они проектируют, часто забывая, насколько важно иметь качественную документацию. Никто не говорит о том, какая крутая инструкция у проекта или какой подробный мануал, но все же документация оказывает большое влияние на успех проекта. Без хорошей сопроводительной документации, пользователи либо не смогут в полной мере раскрыть весь потенциал продукта, либо, что еще хуже, даже не смогут работать с ним. Если все сложится удачно, довольные пользователи будут активно распространять новости о вашем проекте. Охотнее всего они будут это делать после того, как смогут понять программу и разобраться в ней. Помочь им в этом обязана документация, предоставляемая вместе с программным обеспечением.
Тем не менее, слишком многие проекты с открытым кодом снабжены лишь довольно скудной справочной информацией. Есть несколько причин, влияющих на качество документации.
Ниже я привел 13 замечаний, встречающихся у целого ряда проектов. На самом деле их гораздо больше. Здесь перечислены самые грубые, по моему мнению, ошибки. Каждый проект, который попадался мне на глаза, имел по крайней мере 2 или 3 проблемы из этой статьи. Посмотрите, под какие пункты попадает ваше любимое программное обеспечение в независимости от того, кто вы — пользователь или разработчик. Подумайте, что бы вы лично исправили.

Читать дальше →