Задать вопрос
tmman
@tmman
Обои из семерки наконец-то пригодились!

Ведете ли вы документацию для проектируемого сайта или приложения?

Ситуация: вы работаете в студии, сдаете сайт, подписываете договор на сопровождение, на сопровождение сажаете сотрудника-джуниора. Чтобы он не тратил время на "вливание" в проект, то делаете ли вы для таких случаев документацию на проект (от и до: на каком аккаунте сайт, домен, почта; почему это так и не так; откуда это взято и т.д.)?
Если делаете, то с помощью каких инструментов?

p.s. прошу воздержаться от комментариев, что все не так, если вы так не работаете. Я тут мало чего могу изменить, а положение всей команды нужно улучшать.
  • Вопрос задан
  • 1876 просмотров
Подписаться 12 Оценить Комментировать
Пригласить эксперта
Ответы на вопрос 9
sim3x
@sim3x
Доки в отдельном инструменте / сайте / в одном клике от кода = доки никто писать не будет

Доки или в коде или нигде

Если документация относиться не к файлу, а к директории, то казуально пишем ридми.рст прямо в той же директории

Но даже большей описательной силой является багтрекер проекта + его репа
Ответ написан
Комментировать
@JuniorNoobie
Сижу в поддержке, пишу мелкие проекты
Сложно вести документацию к проекту, если требования меняются раз десять на дню. И время, которое тратит lead (senior, middle) на написание развернутой документации, гораздо ценнее времени, которое потратит junior, чтобы вникнуть в проект. Вот если бы можно было писать документацию прямо по ходу написания самого проекта! Но это фантастика и у меня нет знакомых, которым это удается.
Ответ написан
@immaculate
Программист-путешественник
Стараюсь писать так, чтобы все было понятно без документации. Это единственное, что работает. Во всех виденных проектах, кроме Enterprise, моментально начинается рассогласование между документацией и кодом, так как требования меняются ежедневно, а времени на поддержание документации нет.

С деплойментом ситуация такая же: лучше вложить время в разработку скрипта автоматического деплоймента, нежели писать документацию, которая сначала устареет, а затем вообще начнет противоречить практике.
Ответ написан
Делаем с помощью notion.so - храним там базовую документацию, глоссарий понятий, очень краткие описания административных процедур, объяснения почему и как работают некоторые вещи, и конечно - документы на отдельные задачи (если задача крупная и писать полное описание в баг-трекере неудобно). Важно, что с этими документами работает сторона клиента, то есть они сами пишут задачи, вставляют туда скриншоты, etc. После чего написанное ими можно доработать, добавить разъяснения для разработчика - и в процесс.

Но вопрос документации в коде, о котором тут писали, меня сильно беспокоит; нам надо озаботиться этим. Именно для того, чтобы разработчики, особенно новые, видели в более понятном виде общую картину. Конечно, есть какая-то навигация в IDE, но всё равно это не вполне то.

Всю документацию держать в коде нельзя, по моему мнению, поскольку мы хотим привлечь клиента к работе над ней. Но и для разработчика отдельно писать код и отдельно доки - тоже проблема, лишние затраты времени и переключение контекста. Делать это никто не любит. Поэтому и думаю, что нужно иметь два комплекта документации - сугубо для разработки, автогенерированная из кода, и в базе знаний, ориентированная на клиента. Notion мне в этом смысле нравится неимоверно, ничего подобного в других местах я не видел. Хотя нет предела совершенству и хочется ещё большего :)

P. S. Евгений: по поводу literary programming... я пробовал нечто подобное делать в студенческом хобби-проекте, баловался. Но не очень получилось, поскольку линейная последовательность документа вступает в конфликт со структурой программы, имеющей вид графа.

Однако, мне доставляло изрядное удовольствие, что в результате получается не только код на Python, но и неимоверно красивый PDF, сделанный LaTeX, с картинками и формулами. А если исхитриться - можно ведь и прямо из кода всякие картинки генерировать, схемы БД например; красиво ведь будет. Надо как-нибудь вернуться к этой теме, очень уж она интересна.
Ответ написан
@kn0ckn0ck
Продюсер
Да, конечно, используем для этого базу знаний. Под каждый продукт/заказчика в ней есть раздел, где описаны основные правила/аккаунты/пароли/явки.
Ответ написан
@ArcadyZherdev
Если по минимуму усилий, то можно поддерживать API комментируя только публичные методы (а-ля https://ru.wikipedia.org/wiki/Javadoc, https://ru.wikipedia.org/wiki/JSDoc и тому подобное) и впоследствии генерируя документацию.
Легкость подхода в том, что меняя метод ты тут же в коде видишь его описание и меняешь его при необходимости.
Ответ написан
Комментировать
lukoie
@lukoie
Редмайн с базой знаний в вики
Ответ написан
Комментировать
DzodzikovAK
@DzodzikovAK
Java Developer
Писать документацию отдельно - трата времени не только на её написание, но и на сопровождение.

Документацией проекта должны быть тесты (в первую очередь высокоуровневые - например, на Cucumber), код и user stories, описанные в тикетах.
Ответ написан
Комментировать
Andrey_Pletenev
@Andrey_Pletenev
Pletenev.com
Если речь идет об экономии времени на вливании новых людей в проект, то все, что вам нужно, это:
1) Выяснить, отсутствие какой инфрмации приводит к наибольшим трудозатратам нового саппортера
2) Описать нужную информацию при условии, что время, потраченное на описание, будет стоить меньше чем время, которое в противном случае будет потрачено на то, чтобы самостоятельно разобраться и выпытать это у коллег (с учетом времени коллег).
Ответ написан
Комментировать
Ваш ответ на вопрос

Войдите, чтобы написать ответ

Похожие вопросы