SK
Size: a a a
2019 January 25
SK
Вот такой вопрос
SK
Как вы оцениваете временные затраты на написание документации?
KC
Как вы оцениваете временные затраты на написание документации?
вот это тоже интересно
NV
SK
О, благодарен за такое
NV
Кратко: сначала ничего не ясно, потом начинаешь узнавать типичные задачи и предсказываешь сроки точнее
SK
А как определяете завершенность документации? Фидбек от пользователей или оценка руководства?
NV
Документация завершена, когда решает задачу читателя и задачу бизнеса. Про это есть тут: t.me/docops/69
SK
Забавное то, что юзая документацию Gcloud сложно развернуть достаточный инстанс или api
NV
Качество проверяется на нескольких слоях: грамотность текста, структура и понятность, полнота и корректность фактов, соответствие бизнесовой задаче. При этом грамотность и факты — критерии объективные и четко проверяемые. А вот структура, понятность и задача бизнеса — субъективные, но с этим тоже можно жить.
Это всё очень похоже на пирамиду тестирования, я об этом тоже писал: t.me/docops/157
Это всё очень похоже на пирамиду тестирования, я об этом тоже писал: t.me/docops/157
SK
Качество проверяется на нескольких слоях: грамотность текста, структура и понятность, полнота и корректность фактов, соответствие бизнесовой задаче. При этом грамотность и факты — критерии объективные и четко проверяемые. А вот структура, понятность и задача бизнеса — субъективные, но с этим тоже можно жить.
Это всё очень похоже на пирамиду тестирования, я об этом тоже писал: t.me/docops/157
Это всё очень похоже на пирамиду тестирования, я об этом тоже писал: t.me/docops/157
Спасибо, пара сообщений и есть пища для ума.
И все же, хотелось бы услышать, как и что у коллег
И все же, хотелось бы услышать, как и что у коллег
NV
А как определяете завершенность документации? Фидбек от пользователей или оценка руководства?
Фидбек пользователей — это тоже показатель, но его обычно можно получить только после релиза документации. Он как продуктовая аналитика.
L
А как определяете завершенность документации? Фидбек от пользователей или оценка руководства?
Документация завершена, когда она живет, используется, когда в нее вносят пулл реквесты, хотят дополнить, покритиковать, прокомментировать
L
Как наверное и любой продукт
NV
О, спасибо что об этом вспомнила. Согласен. Definition of done задачи на документацию — это когда документацию опубликовали и ей начали пользоваться и, если дока внутренняя, начали контрибьютить в неё.
Про это я тоже писал: t.me/docops/64. Идея пришла от Игоря Цупко @lovely_it_hell.
Про это я тоже писал: t.me/docops/64. Идея пришла от Игоря Цупко @lovely_it_hell.
A
С другой стороны, контрибьюшн можно считать и признаком того, что документация не завершена и есть пробелы
AK
Фидбек пользователей — это тоже показатель, но его обычно можно получить только после релиза документации. Он как продуктовая аналитика.
ну можно ещё исследования проводить. и это можно сделать до релиза. хотя времени занимает безумное количество
NV
С другой стороны, контрибьюшн можно считать и признаком того, что документация не завершена и есть пробелы
Если это дока для пользователей о продукте, то она теряет актуальность с каждой фичей.
Если дока про внутренние процессы в компании, то она точно неполна, потому что один человек не может всё знать. Тут тонкое различие: документация неполна, но задача на её разработку завершена, потому что документация начала жить и собирать знания.
Если дока про внутренние процессы в компании, то она точно неполна, потому что один человек не может всё знать. Тут тонкое различие: документация неполна, но задача на её разработку завершена, потому что документация начала жить и собирать знания.
A
Лично для меня критерий завершенности документа, это когда он четко отвечает на вопросы, поставленные в задаче.
Т.е. если это фича - для кого она, что позволяет и как ее настроить. Если, к примеру, эндпоинт, то это параметры, с которыми на него можно отправлять запросы, тело запроса (если нужно), ответ от сервера, ошибки.
Чтобы точно знать о чем писать, мы в задаче оговариваем definition of done
Т.е. если это фича - для кого она, что позволяет и как ее настроить. Если, к примеру, эндпоинт, то это параметры, с которыми на него можно отправлять запросы, тело запроса (если нужно), ответ от сервера, ошибки.
Чтобы точно знать о чем писать, мы в задаче оговариваем definition of done