Да, в Манифесте гибкой разработки есть один пункт, в котором говорится следующее:

«Рабочее программное обеспечение важнее всеобъемлющей документации»

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

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

Одностраничные документы — это, в конечном счете, то, к чему вы должны стремиться. Эта одна страница должна содержать общий дизайн и концепции, а также направляющую информацию, которая действительно указывает вам, например: репозиторий Git, фрагмент кода или работающее программное обеспечение, которое вы можете использовать, чтобы понять его, и… и т. д. Если вы начнете с общего обзора и некоторого направления, детали низкого уровня всегда можно будет выяснить, если вы знаете, где искать.

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

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

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

  1. Обмен информацией в чистом виде: чтобы вы могли делиться информацией или повторяемыми инструкциями о том, как что-то делается.
  2. Мнение: чтобы вы высказали свое мнение о том, как что-то можно спроектировать или реализовать.
  3. Поиск совета: для вас, чтобы поделиться советом о том, как что-то следует спроектировать или реализовать.

Как профессионалы в области разработки программного обеспечения, мы должны тратить все больше и больше времени на пункты № 2 и № 3 и меньше должны тратить на пункт № 1, который в основном повторяется и может быть легко задокументирован .

Читая эту статью, спросите себя:

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

Спасибо за чтение. Пожалуйста, следуйте за мной здесь, на Medium.com, или загляните в мой личный блог: http://www.almirsCorner.com.

У меня также есть несколько видеороликов на YouTube о разработке программного обеспечения по адресу: http://www.YouTube.com/almirx101.

Альмир Мустафик