Хабр Курсы для всех
РЕКЛАМА
Практикум, Хекслет, SkyPro, авторские курсы — собрали всех и попросили скидки. Осталось выбрать!
Хабр доступен 24/7 благодаря поддержке друзей
Комментарии 33
А что, кто-то читает документацию?
А это то, что по-умному называется положительной обратной связью (кажется). Фичи пилить, быстрее, бизнес требует, срочно, важно! А документацию – ну, там, время будет, черкнём чего-нибудь. Потом возникает желание прочесть-таки документацию и понять, как оно устроено и работает. Вот только документация оказывается липовой – ничего толком нет, не актуальна, непонятна, а то и вообще отсутствует.
Раз, другой, третий – и вот уже есть чёткое понимание, что документацию можно не читать, потому что см. выше. Из чего логически вытекает и текст Вашего комментария.
А вот о последствиях такого подхода к документации никто почему-то не думает. Ну да это не для этого комментария тема…
Раз, другой, третий – и вот уже есть чёткое понимание, что документацию можно не читать, потому что см. выше. Из чего логически вытекает и текст Вашего комментария.
А вот о последствиях такого подхода к документации никто почему-то не думает. Ну да это не для этого комментария тема…
Лично я соглашусь с вашим комментарием. Документацию сложно писать и сложно поддерживать в актуальном состоянии. Когда техписа нет, рано или поздно за документацию забудут. Или не забудут, но описывать будут только новые фичи. А обновлять документы по существующим никто не будет.
И даже будучи техписом, поддерживать документацию сложно. Потому и да, на документацию ругаются. И читать ее не хотят.
У меня пока нет лекарства для этого. Мы сейчас в процессе — продумываем возможные решения этому…
И даже будучи техписом, поддерживать документацию сложно. Потому и да, на документацию ругаются. И читать ее не хотят.
У меня пока нет лекарства для этого. Мы сейчас в процессе — продумываем возможные решения этому…
ага. например, новички проекта или те, кто подменяет автора кода на время отпуска / отгула / больничного / командировки / конференции и нужно что-то поправить/добавить/убрать (и сделать это желательно быстро. читать код — долго, документация помогает).
очень расстраивает [ситуация], когда приходишь в новую компанию, а документация передается из уст в уши, но не через бумагу. при этом со временем часть знаний теряется, необходимый минимум инфы для эффективной работы увеличивается, а времени на это становится всё меньше (у начальства). во избежание как минимум таких ситуаций помогает написание документации. ну хоть какой-то, не обязательно очень подробной.
очень расстраивает [ситуация], когда приходишь в новую компанию, а документация передается из уст в уши, но не через бумагу. при этом со временем часть знаний теряется, необходимый минимум инфы для эффективной работы увеличивается, а времени на это становится всё меньше (у начальства). во избежание как минимум таких ситуаций помогает написание документации. ну хоть какой-то, не обязательно очень подробной.
Сколько работаю техписателем, столько задаюсь тем же вопросом :) Но оказывается, читают.
Мы в компании даже прикручивали инструменты, чтобы смотреть посещаемость документов и собирать обратную связь.
Мы в компании даже прикручивали инструменты, чтобы смотреть посещаемость документов и собирать обратную связь.
Для себя выделила пять причин. Ими делюсь.
- Нет включения в командную работу.
- Нет обратной связи.
- Нет цели.
- Нет контроля.
- Нет ценности.
Шестой пункт забыли: уволили по сокращению штата.
Интересная мысль. Именно в такой компании я сейчас и работаю — мы разрабатываем и внедряем свой продукт.
Это зависит от продукта и отношения к тому, как он должен быть показан и передан потенциальным пользователям.
Есть системы, где без хорошей, актуальной документации не обойтись, потому что интуитивно нельзя понять, как этой системой пользоваться.
Конечно, это уже проблема тех, кто разрабатывает систему. Нормально сделаете — сэкономите на техписателе. Но всегда будут обновления, всегда будут доделки, всегда нужно будет вспомнить, а как было вначале, а что по умолчанию должно быть. И вот тут хоть какая-то документация, но поможет.
Опять же, говорю из своего опыта. Возможно, бывает по-другому. Я еще не сталкивалась с проектами, где документация не была нужна от слова совсем. То, как относились к ней и к процессу ее создания, — это другой вопрос.
Причина — документация это обязательство.
Это зависит от продукта и отношения к тому, как он должен быть показан и передан потенциальным пользователям.
Есть системы, где без хорошей, актуальной документации не обойтись, потому что интуитивно нельзя понять, как этой системой пользоваться.
Конечно, это уже проблема тех, кто разрабатывает систему. Нормально сделаете — сэкономите на техписателе. Но всегда будут обновления, всегда будут доделки, всегда нужно будет вспомнить, а как было вначале, а что по умолчанию должно быть. И вот тут хоть какая-то документация, но поможет.
Опять же, говорю из своего опыта. Возможно, бывает по-другому. Я еще не сталкивалась с проектами, где документация не была нужна от слова совсем. То, как относились к ней и к процессу ее создания, — это другой вопрос.
Нанимать тех писателя с самого старта нет смысла, а где тот момент когда уже пора - не ясно. Когда в редми репозиториев становится слишком много строк?
Думаю, тоже от проекта зависит. Нужно понимать, зачем именно нужен техпис, когда в редми репозитория становится много строк. Что ожидают от человека? Чтобы он это всё привел в порядок? Снес начисто и написал всё заново, но уже четко-красиво, со стайлгайдом для девов в придачу?
Мне, бывало, очень не хватало понимания того, чего именно от меня ожидают. На каком бы этапе это ни было, как бы плохо всё с документацией не было, мне лично хочется одного — понимать, что хотят видеть результатом моей работы. Хотя бы промежуточным. Не говорю про конечный.
Мне, бывало, очень не хватало понимания того, чего именно от меня ожидают. На каком бы этапе это ни было, как бы плохо всё с документацией не было, мне лично хочется одного — понимать, что хотят видеть результатом моей работы. Хотя бы промежуточным. Не говорю про конечный.
Лучше искать работу в компаниях, где документация представляет собой добавленную стоимость продукта, например, где не обойтись без использования API/SDK, где важны примеры, юз кейсы, где есть активное сообщество разработчиков-пользователей, сразу все будут очень заинтересованы. Примеры: Docker, GitLab (там даже есть публичные выложенные карьерные уровни и требования к техписам), Jetbrains, из российских – Selectel вспоминается.
На тему как повышать свою ценность как техписа через соседние области продукта есть отличная статья: www.sentryone.com/blog/effective-technical-writing-is-essential-for-your-organizations-success
ПыСЫ: а добавь статью в хаб Подготовка технической документации?
На тему как повышать свою ценность как техписа через соседние области продукта есть отличная статья: www.sentryone.com/blog/effective-technical-writing-is-essential-for-your-organizations-success
ПыСЫ: а добавь статью в хаб Подготовка технической документации?
Соглашусь со всем, что написано автором. Но на его месте может быть не только технический писатель :). Вообще ценность технического писателя возрастает в прямой зависимости от количества пользователей продукта и в обратной от качества работы разработчика. А в России очень много кампаний где результат сдается, выплачиваются деньги ну и на этом все. В таких случаях технический писатель точно не почувствует себя нужным, но и разработчики, если бы задумывались над ситуацией, то тоже чувствовали себя также :)
Интересная статья, спасибо.
Жаль, что здравая мысль «налаживайте процесс вычитки документации у себя в команде. Давайте своему техписателю обратную связь. Как положительную, так и конструктивно отрицательную, если вам или пользователям что-то не нравится.» иногда утрируется в компаниях и вызывает противоположный эффект. Т.е. те, кому поручили (может в этом и причина) вычитку, читают документ «наискосок», в перерывах между встречами/совещаниями/обедами и вместо конструктива выдают результат «документация плохая, всё переделать».
Фактически, такая обратная связь даже хуже, чем её отсутствие.
Жаль, что здравая мысль «налаживайте процесс вычитки документации у себя в команде. Давайте своему техписателю обратную связь. Как положительную, так и конструктивно отрицательную, если вам или пользователям что-то не нравится.» иногда утрируется в компаниях и вызывает противоположный эффект. Т.е. те, кому поручили (может в этом и причина) вычитку, читают документ «наискосок», в перерывах между встречами/совещаниями/обедами и вместо конструктива выдают результат «документация плохая, всё переделать».
Фактически, такая обратная связь даже хуже, чем её отсутствие.
Большое спасибо за отзыв!
Да, знаю о таких случаях. И в моей практике тоже было «переделай всё». Но помог главный разработчик проекта тогда. Он вычитал сам и сказал бизнесу, что всё в порядке. Повезло с человеком :)
Как лекарство от «переделай всё»: можно делиться с другими авторитетными subject matter experts и получать обратную связь от них. Можно общаться с юзерами. (Последнее менее реально, согласна.) Но опять-таки, сложность в том, что такое общение зачастую должно быть одобрено менеджментом.
Если бы мне такое долго не одобряли, в один прекрасный день меня бы в такой компании не стало.
Да, знаю о таких случаях. И в моей практике тоже было «переделай всё». Но помог главный разработчик проекта тогда. Он вычитал сам и сказал бизнесу, что всё в порядке. Повезло с человеком :)
Как лекарство от «переделай всё»: можно делиться с другими авторитетными subject matter experts и получать обратную связь от них. Можно общаться с юзерами. (Последнее менее реально, согласна.) Но опять-таки, сложность в том, что такое общение зачастую должно быть одобрено менеджментом.
Если бы мне такое долго не одобряли, в один прекрасный день меня бы в такой компании не стало.
рано или поздно у всех появляется желание поменять что-то в жизни
Здравствуйте. У Вас отличная статья, что называется, о наболевшем! Я столкнулся со всеми перечисленными Вами пунктами, но выходил из ситуации самостоятельно. Если позволите, попробую кратко изложить свой опыт в режиме «что делал-что получилось», может, кому-то пригодится.
Причина 1. Нет включения в командную работу. Самая рядовая, потому что огромное число работодателей не в курсе, что делает тех.писатель. Более того, данная позиция зависит от специфики компании/продукта. На моей самой первой работе так и было.
Ну здесь, наверное, не напрашиваться стоит, а уверенно донести мысль, что считаешь необходимым свое присутствие на всех мероприятиях команды, объясняя зачем это нужно в контексте твоей работы. Если тимлид/начальник не слышит после первого обращения, можно не переживать — из такой команды бегут и разработчики.
Что делал я: вежливо и уверенно объяснял, что я должен присутствовать на этих мероприятиях.
Результат: со следующей недели я уже участвую во всех совещаниях, в том числе, в неформальных переговорах на кухне.
Причина 2. Нет обратной связи. Очень вытекает из первой причины. Не понимают, кто такой тех.писатель, и по каким критериям его оценивать. Самое очевидное — наличие документа. Документ готов — хорошо, но читать его нет времени. В этом случае также ничего постыдного нет настойчиво просить ознакомиться с документом.
Что делал я: показывал отдельные топики всем, кому мог, когда видел, что время и обстоятельства располагают.
Результат: нашел общий язык с разработчиками, после чего они сами в последующих кейсах просили почитать/ознакомиться.
Причина 3. Нет цели. Здесь работа обоюдная: и тимлида/начальника, и писателя. В университете учат всегда в рефератах/курсовых начинать с цели работы. То же самое и на профессиональном поле. Первое, что нужно уяснить любыми возможными средствами — для кого и зачем пишем документ.
Что делал я: буквально надоел менеджменту среднего звена своими вопросами, кто же будет пользоваться разрабатываемым документом, и для чего я работаю в данный момент.
Результат: со временем (не сразу!) стал четко разграничивать документы по проектам с указанием степени их значимости и равноценно ответственно относиться к разработке каждого. Вроде как, даже мотивация появилась расти дальше.
Причина 4. Нет контроля. Организовывать контроль самому себе — единственный верный выход из данной ситуации.
Что делал я: попытался декомпозировать поток задач на листке бумаги, а уже основательно по каждой буквально сел на шею начальнику. А также начал сам отчитываться по корпоративной почте за каждое выполненное поручение в рамках своей же декомпозиции.
Результат: начальник в курсе, на какой стадии сейчас ведется разработка документации. Вся переписка на сервере корпоративной почты — можно доказать, чем я занимался и в какой день.
Причина 5. Нет ценности. Здесь мне пришлось тоже брать быка за рога, ибо ненавижу находиться в состоянии потерянности.
Что делал я: перестал сам думать, что моя работа никому не нужна. Глубже изучил предметную область, которую документирую, чаще обращался с вопросами к разработчикам и лиду/начальнику. Проявлял жаркую любознательность по каждому техническому затыку со своей стороны (по технологическим стекам изрядно надоел вопросами аналитику).
Результат: спустя два месяца не просто говорил на одном языке со всем отделом, но и имел наглость предложить свое видение по тому или иному вопросу.
Вывод: проявляйте инициативу. Забудьте, что инициатива наказуема. Не поощряется здесь — выстрелит в другом месте. Возможно, мой опыт слишком субъективный, и мне просто везло с руководством среднего звена (удавалось до них достучаться), но уверенность и понимание, чего хочешь именно ты, города берет, в чем я убедился на последующих проектах. Из компании, на опыт в которой была отсылка, я уже, кстати, ушел.
Напоследок я бы выделил шестую причину, почему тех.писатель уходит, и она может быть более распространена в проф.среде и менее очевидна на первый взгляд.
Причина 6. Нет путей развития как специалиста. Я очень рвался работать в серьезных системах по документированию и практиковать на реальных кейсах подход docs-as-a-code, но компании этого не надо. Всех устраивают отлаженные бизнес-процессы здесь и сейчас, но почему-то на рынке труда на позиции senior почти везде просят уверенные знания Madcap Flare, Framemaker, Robohelp, oXygen и многие другие. А где им взяться, если твоя текущая компания даже не собирается пробовать в эту сторону, не говоря уже про настройку и запуск в рамках производственного процесса? На одних триалах далеко не уедешь, а вся текущая работа настолько выматывает за день (10-12 часов), что вечерами делать свои петы — дело очень тяжелое и далеко не всегда эффективное. Сейчас уже трудно найти команду, где тебе дадут время освоиться с 0 не просто азам, но и уверенной корпоративной работе в Jira+Confluence, а тем более — в Git.
Причина 1. Нет включения в командную работу. Самая рядовая, потому что огромное число работодателей не в курсе, что делает тех.писатель. Более того, данная позиция зависит от специфики компании/продукта. На моей самой первой работе так и было.
Нет, он не должен самостоятельно напрашиваться. Не должен сам писать своему менеджеру и проситься на митинг. Если менеджер приглашает разработчика – создателя фичи – на демо, почему он не приглашает человека, который будет объяснять, как эта фича работает, – техписателя?
Ну здесь, наверное, не напрашиваться стоит, а уверенно донести мысль, что считаешь необходимым свое присутствие на всех мероприятиях команды, объясняя зачем это нужно в контексте твоей работы. Если тимлид/начальник не слышит после первого обращения, можно не переживать — из такой команды бегут и разработчики.
Что делал я: вежливо и уверенно объяснял, что я должен присутствовать на этих мероприятиях.
Результат: со следующей недели я уже участвую во всех совещаниях, в том числе, в неформальных переговорах на кухне.
Причина 2. Нет обратной связи. Очень вытекает из первой причины. Не понимают, кто такой тех.писатель, и по каким критериям его оценивать. Самое очевидное — наличие документа. Документ готов — хорошо, но читать его нет времени. В этом случае также ничего постыдного нет настойчиво просить ознакомиться с документом.
Что делал я: показывал отдельные топики всем, кому мог, когда видел, что время и обстоятельства располагают.
Результат: нашел общий язык с разработчиками, после чего они сами в последующих кейсах просили почитать/ознакомиться.
Причина 3. Нет цели. Здесь работа обоюдная: и тимлида/начальника, и писателя. В университете учат всегда в рефератах/курсовых начинать с цели работы. То же самое и на профессиональном поле. Первое, что нужно уяснить любыми возможными средствами — для кого и зачем пишем документ.
У документации должна быть цель. Документация призвана решать конкретную проблему конкретного человека. Будь то пользователь-начинашка, который ищет кнопку “Сделать хорошо” в интерфейсе, или разработчик, которого подключают на новый проект, – документация должна помочь такому пользователю или разработчику.
Что делал я: буквально надоел менеджменту среднего звена своими вопросами, кто же будет пользоваться разрабатываемым документом, и для чего я работаю в данный момент.
Результат: со временем (не сразу!) стал четко разграничивать документы по проектам с указанием степени их значимости и равноценно ответственно относиться к разработке каждого. Вроде как, даже мотивация появилась расти дальше.
Причина 4. Нет контроля. Организовывать контроль самому себе — единственный верный выход из данной ситуации.
Что делал я: попытался декомпозировать поток задач на листке бумаги, а уже основательно по каждой буквально сел на шею начальнику. А также начал сам отчитываться по корпоративной почте за каждое выполненное поручение в рамках своей же декомпозиции.
Результат: начальник в курсе, на какой стадии сейчас ведется разработка документации. Вся переписка на сервере корпоративной почты — можно доказать, чем я занимался и в какой день.
Причина 5. Нет ценности. Здесь мне пришлось тоже брать быка за рога, ибо ненавижу находиться в состоянии потерянности.
Что делал я: перестал сам думать, что моя работа никому не нужна. Глубже изучил предметную область, которую документирую, чаще обращался с вопросами к разработчикам и лиду/начальнику. Проявлял жаркую любознательность по каждому техническому затыку со своей стороны (по технологическим стекам изрядно надоел вопросами аналитику).
Результат: спустя два месяца не просто говорил на одном языке со всем отделом, но и имел наглость предложить свое видение по тому или иному вопросу.
Вывод: проявляйте инициативу. Забудьте, что инициатива наказуема. Не поощряется здесь — выстрелит в другом месте. Возможно, мой опыт слишком субъективный, и мне просто везло с руководством среднего звена (удавалось до них достучаться), но уверенность и понимание, чего хочешь именно ты, города берет, в чем я убедился на последующих проектах. Из компании, на опыт в которой была отсылка, я уже, кстати, ушел.
Напоследок я бы выделил шестую причину, почему тех.писатель уходит, и она может быть более распространена в проф.среде и менее очевидна на первый взгляд.
Причина 6. Нет путей развития как специалиста. Я очень рвался работать в серьезных системах по документированию и практиковать на реальных кейсах подход docs-as-a-code, но компании этого не надо. Всех устраивают отлаженные бизнес-процессы здесь и сейчас, но почему-то на рынке труда на позиции senior почти везде просят уверенные знания Madcap Flare, Framemaker, Robohelp, oXygen и многие другие. А где им взяться, если твоя текущая компания даже не собирается пробовать в эту сторону, не говоря уже про настройку и запуск в рамках производственного процесса? На одних триалах далеко не уедешь, а вся текущая работа настолько выматывает за день (10-12 часов), что вечерами делать свои петы — дело очень тяжелое и далеко не всегда эффективное. Сейчас уже трудно найти команду, где тебе дадут время освоиться с 0 не просто азам, но и уверенной корпоративной работе в Jira+Confluence, а тем более — в Git.
Полностью соглашусь и поддержу все пункты! Читаю и понимаю, что очень во многом поступала так же, как и вы. И это отличные рекомендации!
В моем случае я однажды просто устала. Устала доказывать. Эта усталость накапливалась, а конечное решение было однозначно принято после одного случая с новым проектом. Если коротко и чтобы не нарушать NDA, мне дали 5 дней на документирование проекта, который длился 3 или 4 месяца. Подключили на последней неделе проекта в понедельник с напоминаем о том, что два из трех разработчиков проекта уходят в пятницу. Хотя задолго до этого я спрашивала о документации. Мне говорили «не надо».
Вот тут и бомбануло.
Наверно, дело в моем характере.
Я очень уважаю здоровую напористость и уверенность в людях. Когда вы можете доказывать и убеждать, даже если первые 10 раз вас не хотят слушать. И здорово, когда вы добиваетесь уважения и к вам прислушиваются!
У меня просто не хватило для этого сил, выдержки и желания тогда.
В моем случае я однажды просто устала. Устала доказывать. Эта усталость накапливалась, а конечное решение было однозначно принято после одного случая с новым проектом. Если коротко и чтобы не нарушать NDA, мне дали 5 дней на документирование проекта, который длился 3 или 4 месяца. Подключили на последней неделе проекта в понедельник с напоминаем о том, что два из трех разработчиков проекта уходят в пятницу. Хотя задолго до этого я спрашивала о документации. Мне говорили «не надо».
Вот тут и бомбануло.
Наверно, дело в моем характере.
Я очень уважаю здоровую напористость и уверенность в людях. Когда вы можете доказывать и убеждать, даже если первые 10 раз вас не хотят слушать. И здорово, когда вы добиваетесь уважения и к вам прислушиваются!
У меня просто не хватило для этого сил, выдержки и желания тогда.
Отличные рекомендации! Спасибо, что поделились опытом. Жаль, что среди технических писателей не так много людей, готовых проявлять инициативу и чего-то добиваться. Мне кажется, что двигателем здесь может быть именно «Я очень рвался работать в серьезных системах по документированию и практиковать на реальных кейсах подход docs-as-a-code», т.е. желание самосовершенствования, роста в проф.знаниях и понимание как и куда хочется расти.
Впрочем, это касается не только техписов, как и вся статья :)
Впрочем, это касается не только техписов, как и вся статья :)
Согласен на 100% и поступал точно так же те 5+ лет, которые работал в этой роли в прошлом. Отдельно отмечу шестую причину, по которой я вообще ушёл из этой специализации (и ни разу об этом не пожалел):
Причина 6. Нет путей развития как специалиста.
В какой-то момент я познакомился с single sourcing в целом и DITA в частности. Тут есть где развернуться :) Но проектов, где это используется либо согласны это внедрять, — единицы.
Далее — если ты технический писатель и только технический писатель, у тебя действительно нет путей развития как специалиста. Спустя годы ты будешь всё легче находить работу, но по-прежнему будешь тем самым «ты кто такой и что тут делаешь?», пользоваться примитивными инструментами и иметь лишь поверхностные знания технологий, о которых пишешь. В лучшем случае ты будешь расти в лида/руководителя команды техписов, но это только в крупной компании и это уже вертикальное развитие, не всем такое нужно.
Если в продукте много интерфейсов взаимодействия с пользователем, можно расширить свою квалификацию в сторону UX — здесь тоже важна информационная архитектура, о которой имеет понятие хороший технический писатель, даже появились специалисты UX Writer. Ну и ценность юзабилити в индустрии в целом понимают больше, чем ценность документации.
И последняя «ложка дёгтя»: есть устойчивый глобальный тренд на автогенерацию документации и чат-ботов. Это не значит, что такие специалисты исчезнут, но спрос на них будет снижаться.
Причина 6. Нет путей развития как специалиста.
В какой-то момент я познакомился с single sourcing в целом и DITA в частности. Тут есть где развернуться :) Но проектов, где это используется либо согласны это внедрять, — единицы.
Далее — если ты технический писатель и только технический писатель, у тебя действительно нет путей развития как специалиста. Спустя годы ты будешь всё легче находить работу, но по-прежнему будешь тем самым «ты кто такой и что тут делаешь?», пользоваться примитивными инструментами и иметь лишь поверхностные знания технологий, о которых пишешь. В лучшем случае ты будешь расти в лида/руководителя команды техписов, но это только в крупной компании и это уже вертикальное развитие, не всем такое нужно.
Если в продукте много интерфейсов взаимодействия с пользователем, можно расширить свою квалификацию в сторону UX — здесь тоже важна информационная архитектура, о которой имеет понятие хороший технический писатель, даже появились специалисты UX Writer. Ну и ценность юзабилити в индустрии в целом понимают больше, чем ценность документации.
И последняя «ложка дёгтя»: есть устойчивый глобальный тренд на автогенерацию документации и чат-ботов. Это не значит, что такие специалисты исчезнут, но спрос на них будет снижаться.
Да, хороший пункт про развитие. Соглашусь. Когда ты в команде один — расти действительно некуда.
Можно трансформироваться в бизнес-аналитика или менеджера проекта, как вариант. Мне предлагали и предлагают именно эти два пути на будущее.
Но в того же бизнес-аналитика лучше переходить в своей же команде, чтобы набраться опыта. И потом уже как бизнес-аналитик идти в другую компанию.
Можно трансформироваться в бизнес-аналитика или менеджера проекта, как вариант. Мне предлагали и предлагают именно эти два пути на будущее.
Но в того же бизнес-аналитика лучше переходить в своей же команде, чтобы набраться опыта. И потом уже как бизнес-аналитик идти в другую компанию.
Лично я уходил однажды из-за фразы «Надо быть внимательнее», произнесенной мне в 1000-й раз.
За 3 года не удалось донести до руководства понимание, что документацию должен кто-то «тестировать» (вычитывать), и в идеале не 1 человек. То есть, код программистов в конторе проходит тестирование, даже не в одну итерацию, а текст нет. Хотя текст — это по сути тот же код, только он читается не программой, а человеком. Давайте тогда уволим тестировщиков и скажем прогерам быть внимательнее, а то что это они.
А ошибки происходят не потому, что специалист «невнимательный», а потому, что ему даже местами в голову не придет, что есть логический косяк, или есть опечатка, которую замыленный глаз и после 10-го перечитывания не увидит.
Но относятся к этому так: «зачем? это же просто текст! такой и я могу написать! а тебе надо просто быть внимательнее!»
Ну и флаг в руки, раз можете — пишите, а я пошёл.
За 3 года не удалось донести до руководства понимание, что документацию должен кто-то «тестировать» (вычитывать), и в идеале не 1 человек. То есть, код программистов в конторе проходит тестирование, даже не в одну итерацию, а текст нет. Хотя текст — это по сути тот же код, только он читается не программой, а человеком. Давайте тогда уволим тестировщиков и скажем прогерам быть внимательнее, а то что это они.
А ошибки происходят не потому, что специалист «невнимательный», а потому, что ему даже местами в голову не придет, что есть логический косяк, или есть опечатка, которую замыленный глаз и после 10-го перечитывания не увидит.
Но относятся к этому так: «зачем? это же просто текст! такой и я могу написать! а тебе надо просто быть внимательнее!»
Ну и флаг в руки, раз можете — пишите, а я пошёл.
Как-то аж ёкнуло всё внутри от слов
Я бы поступила так же, как и вы. Три года — это вы еще молодец :) Я бы так долго не продержалась. (Но это в силу своего характера, наверно.)
А то, что вычитывать документацию нужно — и не техпису, который ее пишет, — это 100%! Это же как code review. Это нормально и правильно. И я не понимаю тех, кто этого не понимает. Мне с такими сложно.
«зачем? это же просто текст! такой и я могу написать! а тебе надо просто быть внимательнее!»
Я бы поступила так же, как и вы. Три года — это вы еще молодец :) Я бы так долго не продержалась. (Но это в силу своего характера, наверно.)
А то, что вычитывать документацию нужно — и не техпису, который ее пишет, — это 100%! Это же как code review. Это нормально и правильно. И я не понимаю тех, кто этого не понимает. Мне с такими сложно.
пользователь-начинашка, который ищет кнопку “Сделать хорошо” в интерфейсе, или разработчик, которого подключают на новый проект, – документация должна помочь такому пользователю или разработчику.
Выскажу точку зрения с позиции разработчика.
Документация для пользователя в целом полезна, как общее описание системы. Она, при грамотном использовании, сокращает время ознакомления с проектом. Но, специальная документация для разработки в большинстве случаев уже давно ушла в прошлое (по большей части).
Если в проекте код написан соответствующим образом, то разобраться в его работе можно и без документации. Плюс во многих компаниях те же API и прочий функционал, а также требования ко всему этому документируются по мере развития системы аналитиками и самими разработчиками в Confluence (или аналогичных продуктах) самостоятельно.
Поэтому писать development guide целесообразно только когда проект в той или иной степени предназначен для использования при разработке другого ПО (библиотеки, информационные системы с API для интеграции со сторонними системами и т.п.).
Другое дело, когда в коде может разобраться в лучшем случае только его автор, нет базы знаний, требования не оформлялись должным образом и т.д. Но, в таких случаях даже от документации толку мало потому, что проблема не в ней или её отсутствии, а в самой постановке рабочего процесса и «культуре производства».
P.S.
налаживайте процесс вычитки документации у себя в команде.
Всё хорошо, когда бывает кстати и меру.
Во многих проектах (если брать серьёзные проекты) объём документации (различные руководства, спецификации) измеряется десятками, а часто и сотнями страниц для каждого тома. Как Вы думаете, сколько нужно времени хотя бы на то, чтобы всё это вычитать? Не говоря уже о том, что бы прочитанный материал был понят и усвоен…
Спасибо, что поделились мыслями. Интересно узнать мнение разработчика на этот счет, правда.
Документация для разработчика — здесь имела ввиду бизнес-описание фичей (что это? зачем? как оно должно работать? какой результат юзер должен получить). У нас есть такое требование к документам. Но опять же мы говорим про разные типы документов. Бизнес-описание фичи (такой себе пресс-релиз) и документация API — это две очень разные вещи.
Что касается «культуры производства», да, часто именно из-за нее документации либо нет, либо она есть, но ею нельзя пользоваться.
По поводу вычитки. Говорю как техпис и только из своего опыта. Уверена, что бывает по-другому. Вычитывать огромный обьем материалов за один раз — дело неблагодарное. Привести в порядок всю существующую документацию, плюс и ту, которой много лет, невозможно. Всегда будет что-то устаревшее. Пока от этого нет лекарства, насколько я знаю.
Как мы пытаемся с этим бороться: Всю боевую мощь техписов бросают на описания новых фичей. Если новая фича как-то связана со существующей, а по существующей есть документация — эта документация проверяется в рамках задачи на новую фичу. Время тоже на это закладывается. Старая документация либо правится, либо сносится в ноль и переписывается.
НО! Так работаю я, в компании, где так можно и за это не ругаются. И я говорю всё же о пользовательской документации. НЕ спецификациях или development guides. Этим у нас занимается архитектор. Пока во всяком случае. Поэтому стратегию вычитки и правок старой документации для себя я пока выработала. Уверена, что буду ее менять со временем.
А то, что даже при таком подходе документация неактуальная всё равно останется — это факт. Пока с ним приходится мириться. Хоть это больно. И решения у меня пока нет.
Документация для разработчика — здесь имела ввиду бизнес-описание фичей (что это? зачем? как оно должно работать? какой результат юзер должен получить). У нас есть такое требование к документам. Но опять же мы говорим про разные типы документов. Бизнес-описание фичи (такой себе пресс-релиз) и документация API — это две очень разные вещи.
Что касается «культуры производства», да, часто именно из-за нее документации либо нет, либо она есть, но ею нельзя пользоваться.
По поводу вычитки. Говорю как техпис и только из своего опыта. Уверена, что бывает по-другому. Вычитывать огромный обьем материалов за один раз — дело неблагодарное. Привести в порядок всю существующую документацию, плюс и ту, которой много лет, невозможно. Всегда будет что-то устаревшее. Пока от этого нет лекарства, насколько я знаю.
Как мы пытаемся с этим бороться: Всю боевую мощь техписов бросают на описания новых фичей. Если новая фича как-то связана со существующей, а по существующей есть документация — эта документация проверяется в рамках задачи на новую фичу. Время тоже на это закладывается. Старая документация либо правится, либо сносится в ноль и переписывается.
НО! Так работаю я, в компании, где так можно и за это не ругаются. И я говорю всё же о пользовательской документации. НЕ спецификациях или development guides. Этим у нас занимается архитектор. Пока во всяком случае. Поэтому стратегию вычитки и правок старой документации для себя я пока выработала. Уверена, что буду ее менять со временем.
А то, что даже при таком подходе документация неактуальная всё равно останется — это факт. Пока с ним приходится мириться. Хоть это больно. И решения у меня пока нет.
Документация для разработчика — здесь имела ввиду бизнес-описание фичей (что это? зачем? как оно должно работать? какой результат юзер должен получить).
Обычно всё это описывается в требованиях и это вотчина аналитиков. Пока аналитики не напишут в ТЗ или тот же Confluence требования для новой фичи или доработки старой, задача в разработку идти не должна. И техпис, хотя бы, до завершения описания требований, по хорошему не должен её касаться. Просто у вас в компании видимо по «доброй» традиции решили сэкономить на аналитиках и отдать их работу техписам со всеми вытекающими.
Говорю не в упрёк. На самом деле в очень многих компаниях подобная печаль.
Очень хорошая статья, виден серьёзный опыт автора :)
Я бы добавил лишь одну мысль: технический писатель — это не человек, а роль. В зависимости от проекта эту роль может выполнять разработчик, менеджер проекта, аналитик, специалист по разработке документации, команда специалистов по разработке документации (примеры из реальных проектов, крупных и мелких, заказных и продуктовых). При этом все 5 тезисов абсолютно релевантны этой роли, особенно когда она выполняется отдельным специалистом и такой специалист один :)
Я бы добавил лишь одну мысль: технический писатель — это не человек, а роль. В зависимости от проекта эту роль может выполнять разработчик, менеджер проекта, аналитик, специалист по разработке документации, команда специалистов по разработке документации (примеры из реальных проектов, крупных и мелких, заказных и продуктовых). При этом все 5 тезисов абсолютно релевантны этой роли, особенно когда она выполняется отдельным специалистом и такой специалист один :)
Зарегистрируйтесь на Хабре, чтобы оставить комментарий
Почему из команды уходит техписатель? У меня на это 5 причин