[IT-стандарты, Управление разработкой, Подготовка технической документации] Такие разные документы: конструкторские vs. user-oriented
Автор
Сообщение
news_bot ®
Стаж: 6 лет 9 месяцев
Сообщений: 27286
Моим любимым русским техническим писателям посвящается
Работа технического писателя – создавать документы на программные продукты, в основном всевозможные руководства пользователя. Разработка документа – дело непростое. Есть очень много подходов и практик. Например, технические писатели в научно-производственных предприятиях часто пишут по ГОСТам или другим отечественным стандартам. Их цель – точно и верно описать продукт. А technical writers в международных компаниях пишут по style guides (Microsoft Manual of Style, например). В этом случае цель, скорее, донести до пользователя, как продукт работает. Здесь фокус смещен с продукта на читателя.
Мне довелось побыть техническим писателем в разных местах, с разными правилами и политиками. Оглядываясь назад, могу сказать, что даже в НИИ тексты можно переориентировать на конечного пользователя, и документы от этого выиграют. Но в ГОСТах про это не пишут. А style guides, во-первых, на английском, а во-вторых, не афишируются в отечественных конторах типа НПП, КБ, и пр. Поэтому есть явная нехватка информации. Я попробую ее восполнить.
Чем отличаются доки для продуктов Yandex, Google, Microsoft, Apple, от old-school документации, созданной инженерами-конструкторами?
Классический инженер пишет так, чтобы продукт был описан максимально полно и правильно + в соответствии с ГОСТами и принятой терминологией. Причем многие термины и определения в ГОСТах устарели и совсем не красят документы. Но это не проблема для конструкторов — никто и не думает, легко ли пользователю понять текст. А вот доки, сделанные для людей, отличаются: они написаны понятным языком и учитывают интересы пользователя. Вопрос приоритетов.
Эти приоритеты и цели автора очень влияют на то, какие получаются документы. Давайте на примерах посмотрим, как это выглядит в жизни:
Конструкторский подход
User-oriented
Простота терминов
Щелчком ЛКМ манипулятора типа «мышь» нажмите на значок папки.
Щелкните по значку папки.
Квалификация читателя
Если писать по ГОСТам 20-го века, то нужно объяснять даже такие элементарные операции, как копирование. Потому что раньше это было непонятно.
Читатель знает, как пользоваться компьютером, и документы не объясняют элементарных вещей.
Подробность
Щелчком ПКМ нажмите на значок файла на рабочем столе. В открывшемся меню выберите «Копировать». Затем в проводнике откройте папку, в которую вы хотите скопировать файл. Щелчком ПКМ откройте выпадающее меню и выберите «Вставить».
Скопируйте файл в нужную папку.
Последовательность изложения
Последовательное изложение от и до, без прикрас. Пользователь должен прочитать ВСЁ. Потом он должен сам догадаться, что ему нужно, а что нет.
Пользователь не хочет читать ВСЁ, он хочет перемещаться по темам нелинейно. Поэтому изложение разделено на отдельные самостоятельные статьи, чтобы из них читатель сложил свой собственный сценарий.
Навигация
Есть только содержание. Все остальное – чтение по порядку, никаких перемещений.
Всевозможные интерактивные ссылки: на разделы, на серию разделов в одном сценарии, и т.д. Пользователь хочет перемещаться по темам не линейно, а по своему сценарию.
Тип контента
Все вперемешку: тут тебе и теория, и немного примеров, и процедура, и таблица, чтобы понятнее было.
Котлеты отдельно, мухи отдельно. Есть топики только процедурные, есть только объясняющие. И между ними, конечно, связь через ссылки.
Хочешь понять и подумать – сначала почитай матчасть. Хочешь сделать – бери и делай по шагам. Это разные топики, потому что и цели у них разные.
Такое бывает, что ты смотришь на документы, а они уже морально устарели. Как будто читаешь инструкцию к трактору 1950-х годов. Нужно как-то сделать их более актуальными, но это кажется невозможным. На самом деле, возможно всё. В следующих статьях я разберу пошагово, как именно от огромного устаревшего комплекта документации перейти к легким, понятным, современным докам. Каждый из пунктов таблицы мы разберем в отдельной статье.
Спойлер
SPL
Легко не будет.
===========
Источник:
habr.com
===========
Похожие новости:
- [Разработка мобильных приложений, Управление разработкой, Развитие стартапа] Разработка продукта: в какой парадигме работать?
- [Проектирование и рефакторинг, IT-стандарты] Как писать хорошие комментарии к коду: «зачем», а не «как»
- [IT-стандарты, Терминология IT, Управление продуктом] Как определить метрики для Управления инцидентами (перевод)
- [IT-стандарты, Терминология IT, Service Desk, Управление продуктом] Как определить метрики для процесса Управления проблемами (перевод)
- [Управление разработкой, Управление проектами, Управление персоналом] Переезжайте в YouTrack легко
- [IT-стандарты, Терминология IT] Как создать метрики для Управления изменениями (перевод)
- [IT-стандарты, Законодательство в IT] «Налоговый маневр» в ИТ-индустрии: кто выиграет?
- [Управление разработкой, Управление проектами, Agile, Управление персоналом] Как я хотел разнообразить ретроспективы, а сделал собственную карточную игру
- [Управление разработкой, Управление проектами, Управление персоналом, Карьера в IT-индустрии] Так выглядит эффективная работа техлида (перевод)
- [Управление разработкой, Управление персоналом, DevOps] От кровавого энтерпрайза к командной работе
Теги для поиска: #_itstandarty (IT-стандарты), #_upravlenie_razrabotkoj (Управление разработкой), #_podgotovka_tehnicheskoj_dokumentatsii (Подготовка технической документации), #_dokumentatsija (документация), #_tehnicheskaja_dokumentatsija (техническая документация), #_technical_writer, #_technical_writing, #_docs, #_tehnicheskie_pisateli (технические писатели), #_teksty (тексты), #_blog_kompanii_acronis (
Блог компании Acronis
), #_itstandarty (
IT-стандарты
), #_upravlenie_razrabotkoj (
Управление разработкой
), #_podgotovka_tehnicheskoj_dokumentatsii (
Подготовка технической документации
)
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 23:49
Часовой пояс: UTC + 5
| Автор | Сообщение |
|---|---|
|
news_bot ®
Стаж: 6 лет 9 месяцев |
|
|
Моим любимым русским техническим писателям посвящается Работа технического писателя – создавать документы на программные продукты, в основном всевозможные руководства пользователя. Разработка документа – дело непростое. Есть очень много подходов и практик. Например, технические писатели в научно-производственных предприятиях часто пишут по ГОСТам или другим отечественным стандартам. Их цель – точно и верно описать продукт. А technical writers в международных компаниях пишут по style guides (Microsoft Manual of Style, например). В этом случае цель, скорее, донести до пользователя, как продукт работает. Здесь фокус смещен с продукта на читателя. Мне довелось побыть техническим писателем в разных местах, с разными правилами и политиками. Оглядываясь назад, могу сказать, что даже в НИИ тексты можно переориентировать на конечного пользователя, и документы от этого выиграют. Но в ГОСТах про это не пишут. А style guides, во-первых, на английском, а во-вторых, не афишируются в отечественных конторах типа НПП, КБ, и пр. Поэтому есть явная нехватка информации. Я попробую ее восполнить. Чем отличаются доки для продуктов Yandex, Google, Microsoft, Apple, от old-school документации, созданной инженерами-конструкторами? Классический инженер пишет так, чтобы продукт был описан максимально полно и правильно + в соответствии с ГОСТами и принятой терминологией. Причем многие термины и определения в ГОСТах устарели и совсем не красят документы. Но это не проблема для конструкторов — никто и не думает, легко ли пользователю понять текст. А вот доки, сделанные для людей, отличаются: они написаны понятным языком и учитывают интересы пользователя. Вопрос приоритетов. Эти приоритеты и цели автора очень влияют на то, какие получаются документы. Давайте на примерах посмотрим, как это выглядит в жизни: Конструкторский подход User-oriented Простота терминов Щелчком ЛКМ манипулятора типа «мышь» нажмите на значок папки. Щелкните по значку папки. Квалификация читателя Если писать по ГОСТам 20-го века, то нужно объяснять даже такие элементарные операции, как копирование. Потому что раньше это было непонятно. Читатель знает, как пользоваться компьютером, и документы не объясняют элементарных вещей. Подробность Щелчком ПКМ нажмите на значок файла на рабочем столе. В открывшемся меню выберите «Копировать». Затем в проводнике откройте папку, в которую вы хотите скопировать файл. Щелчком ПКМ откройте выпадающее меню и выберите «Вставить». Скопируйте файл в нужную папку. Последовательность изложения Последовательное изложение от и до, без прикрас. Пользователь должен прочитать ВСЁ. Потом он должен сам догадаться, что ему нужно, а что нет. Пользователь не хочет читать ВСЁ, он хочет перемещаться по темам нелинейно. Поэтому изложение разделено на отдельные самостоятельные статьи, чтобы из них читатель сложил свой собственный сценарий. Навигация Есть только содержание. Все остальное – чтение по порядку, никаких перемещений. Всевозможные интерактивные ссылки: на разделы, на серию разделов в одном сценарии, и т.д. Пользователь хочет перемещаться по темам не линейно, а по своему сценарию. Тип контента Все вперемешку: тут тебе и теория, и немного примеров, и процедура, и таблица, чтобы понятнее было. Котлеты отдельно, мухи отдельно. Есть топики только процедурные, есть только объясняющие. И между ними, конечно, связь через ссылки. Хочешь понять и подумать – сначала почитай матчасть. Хочешь сделать – бери и делай по шагам. Это разные топики, потому что и цели у них разные. Такое бывает, что ты смотришь на документы, а они уже морально устарели. Как будто читаешь инструкцию к трактору 1950-х годов. Нужно как-то сделать их более актуальными, но это кажется невозможным. На самом деле, возможно всё. В следующих статьях я разберу пошагово, как именно от огромного устаревшего комплекта документации перейти к легким, понятным, современным докам. Каждый из пунктов таблицы мы разберем в отдельной статье. СпойлерSPLЛегко не будет.
=========== Источник: habr.com =========== Похожие новости:
Блог компании Acronis ), #_itstandarty ( IT-стандарты ), #_upravlenie_razrabotkoj ( Управление разработкой ), #_podgotovka_tehnicheskoj_dokumentatsii ( Подготовка технической документации ) |
|
Вы не можете начинать темы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Вы не можете отвечать на сообщения
Вы не можете редактировать свои сообщения
Вы не можете удалять свои сообщения
Вы не можете голосовать в опросах
Вы не можете прикреплять файлы к сообщениям
Вы не можете скачивать файлы
Текущее время: 22-Ноя 23:49
Часовой пояс: UTC + 5