Я занимаюсь техническим писанием того или иного рода с 1999 года, когда занимался контролем качества в научно-исследовательском отделении Altec Lansing в Кфар-Сабе, Израиль. В то время мы выпускали инновационные аудиоустройства, такие как (вздох) USB-аудиоустройства, которые работали на Windows ME и 2000. Они содержали ошибки, и их настройка была не такой простой задачей, как сегодня. Нам нужны были документы. У нас были некоторые препятствия, которые пользователям приходилось преодолевать, и нам нужен был способ документировать, в чем они заключаются, каковы были крайние случаи, а также как диагностировать и исправлять все эти проблемы. Он должен был быть красиво упакован, четко отформатирован и доступен пользователям, установившим наше вспомогательное приложение. Я нашел приложение Robohelp, которое используется для создания стандартных справочных приложений в Windows, и добавил файл справки в нашу установку. В ходе процесса контроля качества мы выявляли проблемы, документировали то, что, по нашему мнению, было наиболее важным, и систематизировали это в файл справки, поставляемый в комплекте с устройством. Мне тогда было 19, и у меня не было никакого опыта в этом деле, и это был чрезвычайно наивный процесс. Тем не менее, это казалось правильным поступком для наших пользователей, и мой менеджер прямо не говорил мне не делать этого. Прошло 24 года, и с тех пор я сделал документацию для множества проектов. Масштаб увеличился, и мой взгляд на подобные проекты существенно изменился. У меня есть некоторые мысли о том, что делает документацию хорошей, и я хотел бы поделиться ими с вами, если вам интересно. Основная концепция документации Я хотел бы начать с набора более конкретных правил, которые, по моему мнению, имеют решающее значение для успеха продукта документирования. , поэтому не используйте слова или сложные предложения, чтобы описать то, что можно сказать более простыми словами. По пути вы потеряете пользователей, и это не стоит эго вашего писателя. Документы должны использовать маленькие слова для описания больших идей цветные , потому что личный, понятный набор задач, рассказывающий историю, будет более интересным и запоминающимся для вашего пользователя, чем абстрактный набор инструкций. Документы должны рассказывать историю, когда вы можете , потому что, если серьезно: это несложно. Если в ваших документах нелегко найти что-то, ваши пользователи не найдут то, что им нужно. Документы должны быть доступны для поиска , и это особенно верно, когда речь идет о программных продуктах. Это затрагивает более широкую тему защиты интересов разработчиков, но вкратце: ваши документы должны сопровождаться видеоуроками, примерами реального использования и технической поддержкой в реальном времени. Документы почти всегда являются частью более широкой стратегии — ведь вы можете быть уверены, что все правильно, но без реальных пользователей, как и с любым другим продуктом, вы не будете знать наверняка. Тестируйте и тестируйте еще раз. Документы следует тестировать Целостные документы — это хорошо продуманные продукты Когда вы изучаете новый , концепции и идеи этого языка попадают в ваш набор приемов решения проблем. Это сделает вас лучшим разработчиком программного обеспечения, и, в конце концов, вы создадите лучшее программное обеспечение, потому что вы более осведомлены и способны. язык программирования Моя карьера была сложной и включала в себя множество работ по проектированию программных продуктов, разработке программного обеспечения, технической поддержке и защите интересов разработчиков. Каждая дисциплина повлияла на то, как я думаю и подхожу к другим. Когда я подхожу к проекту технического письма, я руководствуюсь широким взглядом на то, что понадобится пользователю. Я думаю, что это правильный подход к документации: целостно. Документы не являются чем-то четко определенным, и чтобы создавать хорошие документы, нужно быть гибким. Для меня это означает, что вы должны думать о своих пользователях с как можно большего количества точек зрения. Вы не можете ничего принимать как должное, иначе вы подведете какую-то группу пользователей, что окажет негативное влияние на ваш бренд, ваш продукт или ваш бизнес, и от этого будет трудно вернуться. Ваши документы очень часто оказываются решающим фактором для ваших пользователей. Если вы хорошо поработаете, пользователи будут успешно использовать ваш продукт и станут чемпионами вашего бренда. Если вы этого не сделаете, они, скорее всего, никогда больше не будут использовать ваш продукт, потому что ваша документация оставила в их сознании неприятный осадок. Они также сообщат другим. Хороший маркетинг начинается здесь, так что имейте это в виду. Делаем хорошие документы Создание хорошей документации просто означает, что вы должны подходить к ее созданию так же, как и к любому другому процессу создания продукта. Вам нужно: Знайте, почему вы создаете свои документы Знайте, кто ваша целевая аудитория Знайте, каковы их болевые точки Улучшайте свои документы с течением времени Давайте подробнее рассмотрим каждый из них. Знание причин ваших документов часто представляет собой действительно простой вопрос и ответ, лежащий на поверхности. Вы создаете документацию, потому что, если вы этого не сделаете, пользователи останутся незамеченными и не смогут использовать ваш продукт. На более глубоком уровне есть конкретный ответ для вашего варианта использования. У вас есть инструмент разработчика? Это один набор ответов. У вас есть инструмент для дизайна розничной торговли? У вас есть SaaS-продукт для бухгалтерского учета? У вас есть автоматическая кофеварка? Это все отдельные наборы ответов. Форма ваших документов определяется тем, кто будет их использовать. Это онлайн? Оно идет в комплекте с приложением? Это напечатано? Каждой пользовательской базе понадобится что-то еще, и вы должны с самого начала понимать, кто они. Ваша задача — выяснить, что является трудным для каждого из ваших пользователей, и разработать документацию, направляющую их через информативный контент, который решает их конкретную проблему. Самое главное, вы должны знать, что, вероятно, у вас не получится все сделать правильно с первого раза. Это означает, что ваши документы необходимо поддерживать и обновлять по мере того, как ваши продукты растут и меняются с течением времени. Будем надеяться, что это сделано в рамках какой-то структуры, позволяющей легко общаться с теми пользователями, которым вы пытаетесь помочь. Вы должны разговаривать со своими пользователями, прислушиваться к их потребностям и стараться использовать свою документацию, чтобы улучшить их опыт использования вашего продукта. Ваши документы — неотъемлемая часть вашего успеха Я подведу итог, просто подчеркну, насколько критически важны документы. Без них ваши пользователи будут предоставлены сами себе и им придется постоять за себя. Это всегда будет означать меньше случаев успеха, худшее представление о вашем продукте в вашей экосистеме, больше недовольных разработчиков или пользователей и негативное влияние на ваш бренд или компанию. Документы сами по себе являются серьезным подпродуктом, являются инвестицией и должны быть частью вашей более широкой продуктовой стратегии. Также опубликовано здесь.
