Здравствуй, уважаемый All!
После того, как я написал довольно увесистый кусок кода, который можно уже воспринимать как продукт, передо мной горой встала задача: написать к нему инструкцию по эксплуатации и разворачиванию, чтобы инженер по внедрению, мой коллега, мог его внедрить на месте, оттюнить и чтобы оно еще и заработало. А потом ему надо будет мейнтейнить этот продукт, в то время как я буду вводить фичи, фиксить баги, и в минуты плохого настроения ломать обратную совместимость.
Как известно, программисты обычно очень плохо пишут документацию. То есть не так, они ее пишут, конечно, хорошо, но им от этого процесса частенько становится плохо, что сказывается на качестве. Потому что это скучно и неинтересно, документацию писать.
Продукт у меня серверный, конфигурировать и тюнить (главное) его проще, чем оракл, но ассоциации с таковым невольно возникают. К концу цикла разработки ассоциаций будет еще больше, но к счастью, документ я пишу уж точно не для домохозяйки. Я его пишу для человека, дело знающего, но который не склонен помнить мелкие мелочи.
Поэтому я хочу спросить: а как вы обычно пишете документацию к своим творениям? Какие можете дать советы, исходя из того, что я не могу поручить данную задачку кому-то другому? Какие, на ваш вкус, качественные README и INSTALL вы видели в природе и можете посоветовать для вдохновения? И главное: как вы делаете, чтобы написание документации не шло через «не могу»?
Я вот просто затрудняюсь даже, с какой стороны начать. Пробовал несколько раз, потом сам не понимал, что написал.
Извините за неровный почерк, и благодарю, что дочитали до конца.
