Где посмотреть примеры документирования разработки сайта?

Question

[Sanes]

Подскажите, какими инструментами лучше пользоваться и на что обратить внимание. Сейчас есть задача создать относительно крупный и сложный веб-проект и хочется это задокументировать. Чисто для себя, заказчик это не оплачивает, да и не нужно ему это наверное.

Answer 1

[Dimonchik]

readthedocs.org

Answer 2

[Эдуард Тибет]

Вы не обозначили самое главное: ДЛЯ ЧЕГО вам надо писать документацию?

Возможные варианты:
1. "Для галочки" - чтобы сдать заказчику.
2. Для уменьшения стоимости владения - например, чтобы новые/внешние разработчики не спрашивали "как это работает" и не отвлекали.
3. Для облегчения жизни себе - например, чтобы новую версию можно было делать на основе старой и ничего не забылось со временем.
4. Еще варианты....

Это САМЫЕ главные вопросы. Ответьте на них - потом можно будет думать дальше :)

Comments

[Sanes]

А как сами думаете?

[Эдуард Тибет]

В вашем комментарии нет ничего по сути изначального вопроса и моего ответа на него.

P.S. Думать я могу что угодно, но это не поможет вам решить ваш изначальный вопрос (если он еще актуален для вас на текущий момент).

[Sanes]

Эдуард Тибет: Ну очевидно же для чего документация. Чтобы описать выполненые работы человеческим языком. Пользоваться ей может, кто угдно. Хоть новый разработчик, хоть прежний спустя время.

[Эдуард Тибет]

Sanes: в ваших комментариях я совершенно не вижу экономики (т.е. денег). А они должны быть на первом месте, если, конечно, вам платят за результат, а не за проведенное время за монитором. Хорошо... чтобы немного уточнить мои изначальные вопросы, ответьте сначала (просто для себя), на следующие:
- требуются фичи A, B, C.
- документация будут пользоваться H, K, L
- время на постановку процесса/возможная стоимость - S.

После того, как подумаете (а лучше напишите у себя и подумаете), можете здесь озвучить. Тогда станет понятно, что советовать или не советовать.

P.S. Если на ваш общий вопрос люди дают частное решение, то не факт, что оно подходит именно вам. М.б. лучше задать частные вопросы и получить конкретный ответ?

[Sanes]

Эдуард Тибет: С вами кашу не сваришь.

[semenovsanek]

https://cms.skeeks.com/community/blog/322-kak-pisa...

Answer 3

[Валентин]

На мой взгляд, самый верный подход - это метаразметка комментариев из которых потом формируется справочная система.
Мы используем Doxygen.
Все, что нужно делать - это правильно оформлять комментарии к коду.

Answer 4

[semenovsanek]

https://cms.skeeks.com/community/blog/322-kak-pisa... - небольшой опыт использования sphinx-doc