http://coastline.very.lv
Жесть, сколько времени занимает писать инструкции. Даже такие тупые и относительно бесполезные. А я еще хотел полноценный туториал написать. Это ж неделя работы, блин.
За это время можно написать все остальное. Чем и займусь.
Комментарии (11)
я не против комментариев, просто столько в неделю писать можно не напрягаясь.
ну собсна так и есть, дней пять на код, ночь на комменты, ночь на доки.
Не ну ок. Просто документацию-то в любом случае в каком-то виде приходится писать - либо до написания продукта, либо после. В моем случае после даже как-то проще вышло, т.к. изменения в интерфейсе были чуть ли не в каждой альфе, и заранее такое особо не закладывается.
Еще скажи плохо, лол.
я не против комментариев, просто столько в неделю писать можно не напрягаясь.
чем отличается хороший программист от посредственного программиста?
любой программист может написать свой код.
хороший может прочитать и понять чужой код, даже если в нём нет комментариев.
время на поддержки зачастую никому не нужной документации может в разы превышать сам процесс программирования.
главное -- работающий продукт.
Не ну ок. Просто документацию-то в любом случае в каком-то виде приходится писать - либо до написания продукта, либо после. В моем случае после даже как-то проще вышло, т.к. изменения в интерфейсе были чуть ли не в каждой альфе, и заранее такое особо не закладывается.
Если окончательно удариться в бюрократию, то ISO 9001 подразумевают процесс непрерывной документации собсно любого процесса. И это всё неспроста. И по своему опыту убеждаюсь, что если ему по настоящему следовать в разумных пределах - то в конторах не уровня корпораций можно обойтись без техрайтера (и местами без аналитика, а в некоторых особо особенных случаях можно сэкономить на кризис-менеджере), бишь, казалось бы ключевой фигуры этого требования. Да и реально контроль того, что происходит возрастает в разы.
Еще скажи плохо, лол.
фигасе рецепт быстрого, лол.
Но в реальной жизни, как тока кьюэй начинает задавать неудобные вопросы - сразу надо отдать полноценный док спеки. С этим рецептом - реально за неделю сделать SRS с нуля для какой-нить там скажем аппы уровня Кенди Краш описанием всех протоколов общения ихнего говна с тем, что видит энд-юзер, включая интеграции со всем фейсбуковским, апп сторовским, гугл плеевским и прочим говном.
Ну и опять таки, респектабельная и доступная документация повышает шанс продукту быть по душе всем - от разработчика, который порекомендует его юзать (потому что всё понятно и разжёвано), и на вопрос, какие плюсы оно нам даст - просто даст ссылку, до бизнес-аналитика, который глянет в ссылочку и сразу поймёт, что раз такая документация - то и продукт и впрямь облегчает жизнь и процесс. Прям как мой рецепт.
- при девелопменте тагать таски, например для инструкции пользователя буить офегенным иметь таги #UI, #newfunсtionality и какую-нить подобную херню в зависимости что там ваще будет;
- писать таски нормально, как для тупых и ещё тупее:
"1.Экспектед: нажмешь сюда, вот тут высирается вот так. Если не высирается, то вот тут тогда красненькое.
2. Функционал подробно: чтобы это высрало, надо написать здесь, нажмать сюда, пойдёт такой запрос, выйдет такой ответ, это всё провернётся 8,5 раз на половых органах и мы получим желаемое, если провернётся не почасовой стрелке вот тут флаг.
3. Пример кода.
4. Ещё какая-то заюзанная херня и ссылки.
0. Название, которое буит говорить, что там в таске ваще и сразу."
На это уходит лишних минут 10-20 даже при объёмных тасках. По ходу написания хорошего подробного таска, многие нежизнеспособные части идеи отваливаются сразу. Тренируется лапидарность. Да и понимание глубин приходит;
- не просирать таски;
- на этапе тестирования отсортировать таски, таги использовать как названия разделов инструкции, названия тасков как подзаголовки разделов, само описание таска после лёгкой редактуры превращается в прекрасную документацию. После тестов слегка припудрить, добавить специй по вкусу;
- скриншотиков понаделать и сделать хорошую гибридную table of contens/figures, тщательнейше обдумать каким фонтом писать и выработать общий стиль дока,
-
- иметь такой же вершенинг документации, как и у софта, желательно с тейбл оф чейнджес и писать при включённом Track changes.
- Профит.