Вчера я ушел из своего текущего места работы, и я беру на себя обязательство документировать свои проекты, чтобы я мог легко их передать.
Принимая во внимание, что мой код уже прокомментирован по хорошему стандарту, что еще мне нужно собрать, чтобы помочь моим коллегам-разработчикам взять на себя мои проекты?
При работе с новым кодом, написанным кем-то другим, первое, чего не хватает новому парню (или девушке), - это обзор системы. Какие подсистемы есть, какова их цель и где следует искать выполнение данной задачи - некоторые вопросы, которые приходят на ум.
Краткий исходный документ, объясняющий общий дизайн системы (и причины, по которым этот дизайн был выбран), возможно, с некоторыми диаграммами, был бы тем, чем я был бы очень рад получить при работе над частью программного обеспечения, написанного кем-то другим.
Подумайте о том, чтобы сделать свою обзорную документацию на высшем уровне Wiki - она позволяет вашим скоро будущим бывшим коллегам легко редактировать и расширять ее.
И обоснование (как упоминалось) очень полезно: почему вы выбрали решение A, когда решения B и C выглядят намного лучше для случайного наблюдателя? Он может пресечь всевозможные бесконечные дискуссии в зародыше.
Мне жаль, что у меня не было ничего полезного, чтобы сказать здесь, но поскольку получатель кода транслируется через несколько спадов, перебалансировки навыков и т.д., я хотел бы повторить и добавить несколько пунктов к предыдущим ответам.
Я предполагаю, что ваше руководство назначило одного или нескольких людей, чтобы взять на себя вашу работу.
Вы сказали, что вам это не нужно, но сейчас не время добавлять комментарии к коду.
Уже отмечалось, что новому владельцу программного обеспечения нужен обзор на высоком уровне, что делает программное обеспечение и что нужно сделать для этого. Сохраните это краткое изложение и постарайтесь не допустить его в том, "как должно выглядеть программное обеспечение", не беспокойтесь, чтобы перепроектировать систему из могилы.
Затем переходите к практическим вопросам: кто является заинтересованными сторонами, тестерами и кем-то еще, кто был и может участвовать, и знать об этом программном обеспечении.
Где требования других документов и PR, есть ли что-то, что особенно важно в PR, - это предстоящие требования?
Где в управлении версиями есть программное обеспечение, все ли там? Действительно?
Что необходимо для создания программного обеспечения?
Самое ценное время будет потрачено на проверку двух последних пунктов: воссоздайте полную среду сборки из управления версиями и создайте (протестировать/доставить) с нового владельца. Если есть время, исправьте простую проблему.
Удачи в новой работе!
Лично я пишу все свои документы в стиле сверху вниз, сначала давая определения всем терминам (для создания общего словаря), а затем объясняя предмет, о котором идет речь, в широком смысле, уточняя детали дальше документа. Таким образом, этот вид документа, охватывающий все основные части системы, будет очень приятным. Кроме того, было бы неплохо, если бы вы предложили обоснование архитектурных решений в своих проектах.
Это может быть само собой разумеющимся, но если проекты не компилируются/запускаются "из коробки" при первом приходе в новую среду разработки (конечно, они должны), поэтапно, шаг за шагом, как получить все и запустить, спасет новых людей от большой головной боли.
Схемы последовательности UML для любых сложных взаимодействий класса/системы, диаграмм классов для любых более сложных конструкций OO и диаграмм системного уровня, которые показывают, как разные системы и приложения соединяются между собой.
Вы можете объяснить дизайн проекта, как работают некоторые важные функции, и, возможно, вы можете документировать все запланированные улучшения.
Кто-то еще уже упоминал документацию всей вашей инструментальной цепочки, чтобы помочь кому-то настроить среду dev. Еще одна вещь, которая может быть слишком метана, заключается в том, чтобы документировать, почему вы используете эти инструменты.
Ничего хуже, чем начинать где-то новое и планировать вырвать все из MS Word корнями, только чтобы узнать, когда вы держитесь локтем в процессе, который немецкий офис продаж должен иметь, чтобы их отчеты TPS генерировались в этот формат и не может использовать Wizbang JSON, который вы хотели бы заменить.