Как подумать и написать обо всём, что важно
Представьте, что мы с вами придумываем новую фичу и пишем о ней документ (vision, SRS, ТЗ). Именно по этому документу дизайнеры придумают интерфейс, разработчики напишут код, а тестировщики проверят, всё ли получилось правильно.
Нам нужно обдумать и описать несколько аспектов фичи: интерфейс, безопасность, GDPR и другие. Держать всё это в голове довольно сложно.
Кажется, что задачу можно упростить шаблоном документа с заголовками секций про каждый аспект. Но бывает, что для фичи X неактуален аспект Y. Например, она не меняет интерфейс. Что тогда делать с заголовком из шаблона?
✘ Удалить заголовок. Читатель не поймёт, забыл автор про это написать или сознательно убрал.
✘ Оставить заголовок, ничего не писать. Так точно будет впечатление, что автор забыл.
✘ Оставить заголовок и написать «Это неприменимо или не имеет значения для этой фичи». Это засоряет документ и усложняет работу читателя.
Все варианты плохи. Ещё сложнее делегировать разработку фич и написание таких документов. Тогда мы сами становимся непонимающими читателями.
Сергей Егоров, руководитель program manager'ов в Plesk, поделился решением:
В конец документа добавляем табличку-чеклист со списком аспектов. В ней ПМ отмечает каждый аспект: «Описано в документе» или «Неприменимо». Если неприменимо — заголовок можно убирать. Если ничего не отмечено, значит ПМ ещё это не проработал.
✔ Отмечать в отдельном чеклисте: аспект описан / неприменим для этой фичи / конь не валялся.
#docops_workflow
Представьте, что мы с вами придумываем новую фичу и пишем о ней документ (vision, SRS, ТЗ). Именно по этому документу дизайнеры придумают интерфейс, разработчики напишут код, а тестировщики проверят, всё ли получилось правильно.
Нам нужно обдумать и описать несколько аспектов фичи: интерфейс, безопасность, GDPR и другие. Держать всё это в голове довольно сложно.
Кажется, что задачу можно упростить шаблоном документа с заголовками секций про каждый аспект. Но бывает, что для фичи X неактуален аспект Y. Например, она не меняет интерфейс. Что тогда делать с заголовком из шаблона?
✘ Удалить заголовок. Читатель не поймёт, забыл автор про это написать или сознательно убрал.
✘ Оставить заголовок, ничего не писать. Так точно будет впечатление, что автор забыл.
✘ Оставить заголовок и написать «Это неприменимо или не имеет значения для этой фичи». Это засоряет документ и усложняет работу читателя.
Все варианты плохи. Ещё сложнее делегировать разработку фич и написание таких документов. Тогда мы сами становимся непонимающими читателями.
Сергей Егоров, руководитель program manager'ов в Plesk, поделился решением:
В конец документа добавляем табличку-чеклист со списком аспектов. В ней ПМ отмечает каждый аспект: «Описано в документе» или «Неприменимо». Если неприменимо — заголовок можно убирать. Если ничего не отмечено, значит ПМ ещё это не проработал.
✔ Отмечать в отдельном чеклисте: аспект описан / неприменим для этой фичи / конь не валялся.
#docops_workflow
Чеклисты и defensive writing
Из разговора с Сергеем Егоровым вынес ещё одну идею. Когда результат в 99% случаев положительный, люди забывают действительно проверять его и ставят галочку в чеклисте в 100% случаев.
Есть понятие «defensive programming» — когда мы пишем код так, чтобы приложение было устойчиво к ошибкам и непредвиденным обстоятельствам.
Давайте подумаем про «defensive writing». Как сделать текст устойчивым к ошибкам и искажениям человеческого восприятия? В частности, как защититься от привычки ставить галочку, не проверяя?
Вот пара идей:
— Сделать колонки «да» и «нет», чтобы подумать и отметить осознанно.
— Переформулировать из состояния в действие. Например, состояние — «окно закрыто», а действие — «я подёргал и убедился, что окно закрыто».
А как вы пишете чеклисты? Как бы вы решили эту проблему? Приглашаю поделиться идеями в @docsascode.
#docops_workflow #docops_defensive_writing
Из разговора с Сергеем Егоровым вынес ещё одну идею. Когда результат в 99% случаев положительный, люди забывают действительно проверять его и ставят галочку в чеклисте в 100% случаев.
Есть понятие «defensive programming» — когда мы пишем код так, чтобы приложение было устойчиво к ошибкам и непредвиденным обстоятельствам.
Давайте подумаем про «defensive writing». Как сделать текст устойчивым к ошибкам и искажениям человеческого восприятия? В частности, как защититься от привычки ставить галочку, не проверяя?
Вот пара идей:
— Сделать колонки «да» и «нет», чтобы подумать и отметить осознанно.
— Переформулировать из состояния в действие. Например, состояние — «окно закрыто», а действие — «я подёргал и убедился, что окно закрыто».
А как вы пишете чеклисты? Как бы вы решили эту проблему? Приглашаю поделиться идеями в @docsascode.
#docops_workflow #docops_defensive_writing