Легкое документирование

06.04.2014 22:31

Разработка, Технический писатель, Требования

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

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

Разумеется, это не совсем то, к чему стремятся разработчики. Давайте посмотрим, как можно избежать подобной ситуации? Ну, я не знаю … может, стоит попробовать записывать информацию? От вас всего-то и потребуется – одно электронное письмо, следующее сразу за телефонным разговором, или личное общение, в котором будут проговорены слова разработчика по поводу того, что, по его мнению, ему было сказано выполнить. На это не требуется больших усилий, зато впоследствии вы получите отличный контрольный журнал, который непременно вам пригодится, когда возникнет вопрос о том, почему ход разработки системы идет в том или ином направлении.

Идеи для легкого документирования

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

Делайте все незамедлительно. Многие из нас любят откладывать на потом то, что нам совсем не нравится или не хочется делать. При документировании лучше этого не допускать. Лучше всего выполнять этот процесс по горячим следам. Вам же будет легче, так как не придется останавливаться и запоминать. Сразу после окончания общения найдите компьютер или мобильное устройство и запишите краткое содержание беседы.
Найдите хорошие инструменты себе в помощь. Говоря о мобильных устройствах, можно выделить достаточное количество удобных инструментов, которые помогут вам в записи информации. В свое время нам приходилось искать нужное место на wiki и отыскивать неинтуитивный язык разметки, чтобы задокументировать даже самые простые вещи. Теперь же повсеместно используются Evernote и OneNote, и множество подобных им утилит; существуют блоги и микроблоги (разве Twitter не подойдет для вашего проекта?); и даже если все пойдет не так, всегда остается электронная почта. Просто выберите то, что вам больше по душе.
Краткость сестра таланта. Не обязательно писать роман каждый раз, когда вы записываете краткое содержание дискуссии. Даже если вы не умеете использовать Twitter, сделайте вид, что вы всегда отличались краткостью и лаконичностью. Того, что вы сможете выразить 140 символами, будет вполне достаточно для краткого изложения основной мысли. Вероятность того, что документ когда-либо будет прочитан более чем один раз, обратно пропорциональна его размеру.
Сохраняйте там, где потом сможете найти. Запись информации абсолютно ничем вам не поможет, если впоследствии вы не сможете найти то место, где она была записана. Выбирайте наиболее очевидное место для предполагаемого поиска (например, в уже ранее созданном хранилище документации по проекту, в том же месте, в котором вы сохраняете исходный код программы, в электронном письме, предназначенном для всех членов команды), в идеале – это должны быть места, для которых существует возможность электронного поиска. Не стоит записывать информацию просто на доске в кабинете команды (даже, если вы делаете это для того, чтобы потом перезаписать куда-нибудь в более надежное место). Попробуйте записать информацию в нескольких местах и посмотреть, где она потом найдется … вы даже можете собирать метрические данные по тем местам, в которых был найден контент, чтобы выбрать наилучшее место для его хранения! Я знаю, что для многих мои слова покажутся настоящим бредом.

Это должно перейти в разряд привычек

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

Оригинал статьи: http://www.infoq.com/articles/id-rather-be-coding-writing-things-down

Автор: Nate McKie

Попробуйте сейчас!