Рассмотрим гибкий подход. Я имею в виду, что если у вас есть ресурсы времени и отличные навыки письма, чтобы записать каждое дизайнерское решение, которое вы, ребята, принимаете вместе с их обоснованием, просто документируйте все. На самом деле, я предполагаю, что вы не в таком положении. Гибкий подход может помочь с ключевой проблемой для документирования обоснований: вы часто не знаете, какие обоснования были важными, до позднего времени.
Давайте подойдем к проблеме с комплексной точки зрения. У вас, ребята, есть основания для вашего решения. Они прямо сейчас в ловушке, мозги команды. Несмотря на объем получаемой кредитной документации, хранение обоснований в sqishyware не так уж и плохо. На самом деле, мы, как вид, очень хорошо помним важные вещи. Вот почему каждая крупная корпорация обладает «племенными знаниями», даже когда эти корпорации стремятся документировать все эти племенные знания.
Теперь у вас есть проблема. Вы обнаруживаете, что sqiushyware не достаточно хорошо обосновывает. Хорошо, что вы поняли, что есть проблема, и определили, что ее нужно решить! Это не всегда легкий шаг! Таким образом, мы уверены, что решение состоит в том, чтобы перенести часть этого обоснования в документацию. Однако этого недостаточно. Мы никогда не сможем забыть вторую половину головоломки, которая заключается в повторной загрузке логического обоснования в сквош-ПО, когда вам нужно принять решение. Я видел множество команд, которые документируют все как сумасшедшие, но контент на самом деле не организован, чтобы помогать принимать правильные решения, поэтому они в конечном итоге забывают обоснования, даже если они записаны .
Итак, у вас есть два этапа. Вы должны получить обоснование из squishyware и в документацию. Затем вам нужно убедиться, что документация организована достаточно хорошо, чтобы вернуть рациональное обратно в squishyware, когда вам это нужно! Теперь я думаю, что у нас достаточно постановки проблемы, чтобы понять, какие задачи понравятся. Когда вы документируете, вы, как правило, не знаете, кто будет смотреть на это позже или что они ищут. Аналогично, когда вы просматриваете документацию, вы, как правило, не знаете, что ищете (в лучшем случае вы можете знать, когда).
Таким образом, большая компания может попытаться справиться с этим двумя большими блоками. Сначала они могут разработать требования, основанные на том, что нужно людям, когда они изучают документацию. Затем они используют эти требования для создания процесса разработки указанной документации. И если я осмелюсь так сказать, то все будут жаловаться, потому что почти никто точно не знает , как должна выглядеть документация в первый день. Документация всегда неполная, и разработчики всегда жалуются, что этот процесс слишком обременителен.
Время идти проворным.
Я бы посоветовал предпринять активные усилия по улучшению процесса документирования: целых девять ярдов - от программы-хранилища до документации и обратно до программы-хранилища. Признайте заранее, что вы потеряете некоторую информацию, потому что ваш процесс не идеален, но это нормально, потому что вы все еще пытаетесь понять процесс! Вы бы пропустили больше, если бы попытались создать одно решение, подходящее для всех.
Несколько конкретных моментов, на которые я бы посмотрел: * Изучите неофициальную документацию. Формальная документация отличная, но отнимает много времени. Одна из целей документации состоит в том, чтобы выпустить информацию из программного обеспечения разработчика и поместить ее на бумагу. Неформальная документация сводит к минимуму расходы на это.
- Принимаем ненадежные форматы документации. Ничто не будет правильным с первого раза. Лучше получить данные и выяснить, как сделать их надежными позже. Например, вы можете задокументировать свои обоснования в блоке <rationale> </ rationale> или в чем-то подобном, что упростит сбор этих данных позже. Сохранение логических обоснований в пользовательской истории пока просто отлично!
- Никогда не забывайте ценность организации. Узнайте, как вам, как команде, нравится искать обоснования в документации, и попробуйте документировать это. У каждой команды будет свой процесс. В одной из моих команд мы никогда не могли найти билет, на котором было обоснование. Что мы могли бы сделать, так это найти строку кода, которая имела значение, сделать,
svn blameчтобы узнать, когда она изменилась и почему, а затем пойти посмотреть на билеты. Как только мы были там, мы обычно помещали все необходимое объяснение прямо в билет. Это только сработало для нас, узнайте, что работает для вас.
- Органическая документация может расти со временем. Разработчики редко знают, какие обоснования являются наиболее важными в тот день, когда им нужно было это написать. Обычно мы узнаем, какие из них были важны позже. Если у вас есть процесс подготовки документации, которая позволяет разработчикам управлять своим собственным небольшим набором обоснований, важные из них поднимутся на поверхность. Что еще более важно, обоснования могут измениться. Возможно, вы понимаете, что два разных изменения с двумя разными обоснованиями действительно лучше всего описываются одним обоснованием, которое работает для обоих. Теперь между вами и решениями стало меньше контента!