Как я могу документировать чужую прошлую работу? [закрыто]

Мы находимся в плохой ситуации, когда у нас очень мало документации по настройке наших прошлых работников для критически важной системы. Много изменений было сделано в Crystal Reports, объектах базы данных и проприетарных файлах конфигурации / программирования для нашего программного обеспечения ERP.

Текущая документация обычно выглядит примерно так:

Эта программа запускается до выставления счета. Известные ошибки: нет.

Запустите эту программу после установки программного обеспечения X.

Изменены следующие поля в этом отчете: (без объяснения того, как и почему)

Наш IT-магазин небольшой, а в случае программного обеспечения ERP большая часть работы была сосредоточена на одном человеке (это я сейчас), поэтому никто другой здесь не знает, что мы все сделали. ИТ-отдел и отдел бухгалтерии знают обломки (иногда весьма полезные), но этого недостаточно.

Другая проблема заключается в том, что наш бухгалтерский отдел считает, что мы хорошо документированы. Это правда, что мы вели много записей о том, что пошло не так , но очень мало объясняет, что (если вообще что-то было) сделано для решения этих проблем. У нас есть сотни статей, объясняющих ошибки, но документы, объясняющие изменения (как показано выше), почти бесполезны.

Как я могу документировать прошлые изменения, когда я не знаю, что все было сделано? Я могу начать с документирования того, что мы изменили: файлы, таблицы баз данных и т. Д., Которые нам нужны для работы системы. Я также могу задокументировать, что мы делаем ; когда запускаются отчеты, почему людям сказали использовать X report / program. Но когда у одной из этих вещей есть проблема, я всегда возвращаюсь к исходной точке.

Как я могу предварительно задокументировать этот материал для себя и других?

Я думаю, что это бесполезное упражнение. Если это работает, это работает, если это не работает, вы должны это исправить.

Лучший способ документировать старые вещи - это работать над ними, документировать, что вы делаете, и объяснять бизнес-логику (которая, как я полагаю, не была документирована). Это будет большой помощью для любого нового разработчика.

Говоря о документировании старого кода / вещей, кто-то должен был владеть им. Предположим, это ваш нынешний менеджер. Он / она может не иметь полных технических знаний об этом, но будет знать, какие изменения были внесены. В таком случае это не твоя работа. Может быть, менеджер может написать что-нибудь об этом, какие изменения были сделаны. Это было бы полезно сохранить как историю. Если возникают такие проблемы, вы можете покопаться в этих областях, что может быть очень полезно для вас. Но вдаваться в код и документировать изменения довольно бесполезно для ИМО и, вероятно, невозможно.

Откажитесь от ваших усилий, чтобы документировать изменения .

Вместо этого начните документировать, что в настоящее время работает и как . Держите эту документацию актуальной и актуальной, так как вы вносите изменения в будущем.

У вас есть контроль версий?

Можете ли вы решить, что изменилось с этого?

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

Можно ли воскресить старый почтовый ящик разработчиков? (не уверен, является ли это жизнеспособным с вопросами конфиденциальности или нет). Там может быть много информации, которая будет получена при прохождении там.

Обо всем по порядку. Где вы храните свою документацию? Если вы еще этого не сделали, создайте вики. Я предпочитаю докувики сам, и есть даже встроенный vm , если вы так склонны.

Это обеспечивает некоторые важные функции:

• Документы доступны в любом месте локальной сети компании (установка на новый компьютер ...)
• Все документы в одном месте
• Все документы доступны для поиска
• Вы можете сотрудничать (новый коллега, пользователи программного обеспечения)

Теперь, если ваша документация в бумажном виде, тогда я желаю вам всего наилучшего. Если у вас есть документы Word, создайте скрипт импорта .

Наконец, просто используйте материал . Всякий раз, когда вам нужно что-то установить, размещайте заметки в вики. Если вы попали в крайний случай, поместите его в вики. Это то место, где сотрудничество может сиять, поскольку вы заставляете других людей делать работу за вас.

Переходя к более конкретной документации, если вам нужно работать с исходным кодом для различных проектов, убедитесь, что у вас настроена правильная среда разработки ! Для проверки списка вещей у вас должно быть:

• Контроль версий ( мерзавец , ртуть , ископаемый )
• Отслеживание ошибок ( trac , mantis , redmine , ископаемый )
• Система сборки ( автоинструменты , scons , buildbot )
• Управление проектом ( затмение , заданная структура каталогов, плагин редактора )
• Исходная документация (README, TODO, INSTALL, Исходные комментарии)

Наконец, поскольку документация может быть скучной, сделайте ее игрой. Дайте себе «очки» за каждый элемент в вашем контрольном списке, периодически проверяя ваш «счет». Это хороший способ увидеть, чего вы достигли и насколько хорошо. Он также отображает, куда вам нужно идти дальше.

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

Редактировать:

Согласно комментарию ниже, еще одна полезная вещь - это создание диаграмм исходного кода. У Freecode есть вещи , и в этой статье перечислены некоторые из них для популярных языков.

Лучшее, что вы можете сделать, это документировать все, что вы знаете, и попросить всю компанию документировать все, что знают другие. Я предлагаю централизовать документацию в вики или что-то подобное, чтобы у всех был доступ к самой современной документации.

Вы не можете задокументировать то, чего не знаете, поэтому либо пытаетесь узнать, почему что-то было сделано, либо просто оставляете это без документов. Вот почему компании нужно уделять больше внимания документированию, пока те, кто знают, все еще работают там.

Если вы пытаетесь задокументировать какой-либо код, который вы не понимаете, я предлагаю вам написать модульные тесты для проверки функциональности. Таким образом, вы лучше поймете, что делает код, а сами тесты могут служить документацией.

Удачи!

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

Причина того, что этот проект находится в форме документации, в которой вы его нашли, заключается в том, что документация любой работы является второстепенной по отношению к запуску. Так что документируйте, что вы изменили, и выяснили, что делает конкретное поле в базе данных и какой конкретный блок кода, если не для кого-либо, кроме вас.

Вы можете написать автоматизированные поисковые тесты. У них есть несколько преимуществ:

• Вы узнаете, как работает система, когда пишете их

• Они служат исполняемой документацией на будущее

• Если вы запускаете их на регулярной или даже непрерывной основе, они предоставляют хорошую защитную сеть для определения, когда изменения что-то ломают или когда они должны быть обновлены

Я не знаю, возможно ли написать подобные тесты в вашей конкретной среде.