Как написать документацию к программе

Одним из основных направлений деятельности технического писателя является написание технической документации на программное обеспечение.

Разновидностей подобной документации множество: это и спецификации и методики тестирования, и тексты программ, и руководства и всевозможные справки для пользователя. Для удобного использования подобной документации она должна быть кратка по объему, актуальна по содержанию, полна по смыслу.

Существуют два способа написания технической документации.

Способ 1. Написание технической документации для специалистов.

1. Определение необходимой информации. Такая документация будет использоваться специалистами (программистами, разработчиками интерфейса), а значит должная содержать точные сведения по программе. Также могут включаться:
— главные файлы приложения, которые создают разработчики, базы данных, утилиты прочих программ,
— подпрограммы и функции с объяснением назначения каждой из них,
— константы и переменные продукта с указанием способа их применения,

ТЗ для сайта: как составить документацию // #VA

— единая структура программного продукта.

2. Сортировка документации по принципу включения в программный код и создание отдельных документов. Максимальное включение документации в код программы облегчают обновление и сопровождение программного продукта.

3. Инструмент для документирования. Определяется языком, на котором создается данный программный продукт и типом требуемых документов.

Способ 2. Написание технической документации для конечных пользователей.

1. Основание для документации. Документальное сопровождение необходимо для любого программного продукта, чтобы показать пользователям пути его применения и оказать техническое сопровождение. Также в таких документах указываются правовые условия.

2. Определение целевой аудитории. Достаточно редко широкий круг пользователей является специалистами в какой-то конкретной области. Для выделения целевой аудитории:

— определите круг должностей сотрудников, которые будут работать с программным приложением,

— постарайтесь познакомиться с этими людьми и создать свое представление об уровне их подготовки,

— главным в написании технической программы поставьте ответ на вопрос, что может дать данный продукт конкретному пользователю.

3. Выберите формат подачи данных при написании технической документации. Обычно это или справочное руководство, или руководство пользователя.

4. Выберите форму для документов (различные справки, PDF-файлы, печатные руководства и т.д.).

5. Выберите удобный инструмент документирования (программное обеспечение).

Источник: tehpis.ru

Как писать техническую документацию?

Разработка технической документации — сложный кропотливый процесс, во время которого специалист в области разработки программного обеспечения может допустить разного рода ошибки и опечатки. Это чревато тем, что код программного обеспечения перестает работать. Можно этого избежать если писать техническую документацию правильно.

Как документировать код | Doxygen урок

Что такое техническая документация

• Пользовательские. В эту категорию попадают документы, в которых описаны правила эксплуатации того или иного технического средства, сложного ПО. Прочтя этот документ, у пользователя не должно остаться вопросов о том, как эксплуатировать приложение.
• Технические. Содержат информацию, которую могут использовать программисты для внесения корректировки в рабочий код. Данный вид спецификаций позволяет новому сотруднику быстро начать работу над проектом или возобновить написание ПО после перерыва.

Как показывает практика, разработчики не читают сопроводительные бумаги, что говорить про ее составление — это делают лишь единицы. Но ее составление очень важно для поддержания работоспособности проекта.

Виды документации

Существует большое количество видов технической документации, но основными являются 2 типа:

1. Конструкторская, которая включает в себя руководство по эксплуатации прибора, ПО, паспорт изделия, технические условия и пр.
2. Технологическая, в которой разработчики указывают информацию о том, как создается продукт, что необходимо сделать для ремонта оборудования или корректировки программного кода. Программисты дают комментарии, указывают примеры ошибок ПО, которые выводят устройство из рабочего состояния.

Каждый из видов документации очень важен для пользователей, поэтому игнорировать стадию создания документа нельзя.

Что следует учитывать при составлении

Программист, составляя инструкцию, должен следовать правилам хорошего тона. Существуют неформальные правила, которые обязательно следует учитывать:

• Документы нужны не всегда. Как бы это противоречиво не звучало, но если разрабатывается программа для одноразового использования, то смысла в разработке технической документации нет. Лучший пример этому — небольшие скрипты, которые будут применены на практике 1 раз.
• Техническая спецификация для пользователей требуется не везде. Как понять, где надо составлять ее, а где нет? Все зависит от качества кода. Если программист создает его хорошо, то пользователь сможет понять, зачем он нужен, прочтя лишь одно название. Если же разработчик использует API или фреймворк, то эти бумаги позволят программисту использовать классы и методы при отсутствии возможности чтения исходного кода.
• Техническая документация должна быть точной. Программист должен выражать собственные мысли и идеи очень точно и ясно. Описывать следует каждый фрагмент кода, для этого рекомендуется создавать короткие определения.
• Все сопроводительные проекты должны быть емкими, без воды. Все комментарии разработчик должен составлять сухо. Не стоит шутить, использовать замысловатые фразы, метафоры и иные литературные методы украшения речи. Ясности это не добавит, только запутает коллег.
• Техническая документация не должна содержать старый код. Хранить старые методы и операторы не следует, так как это мусор, который только запутает разработчика. Поэтому все документы, которые не имеют отношения к ПО, следует устранять. Если существует сомнение в том, что xml-код может потребоваться в дальнейшем, то для ее хранения лучше использовать систему контроля версий.

Если соблюдать эти простые правила, то чтение документов не будет проблемой для начинающих программистов и более опытных коллег, которым предстоит работа со сторонним ПО.

Где писать

Если необходим xml-код, то вариантов для его создания существует множество. Для этого можно прибегнуть к использованию Microsoft Word или Google Docs. Последняя программа позволяет предоставить пользователям онлайн-доступ к документу. Главное преимущество этого состоит в том, что по необходимости можно вносить корректировки, если информация устарела.

Другой способ создания документов — написание кода непосредственно в программе. Это позволяет разработчикам ПО в любой необходимый момент получить информацию по коду. Как это сделать? Самым простым способом являются комментарии, которые дают программисты при разработке кода.

Если выбор падает, например, на С#, то здесь предусмотрено два основных типа комментариев:

• Однострочные, в которых можно уместить 2−3 параметра.
• Многострочные, где разработчик может указать необходимую информацию.

Когда идет сборка, компилятор игнорирует многострочные комментарии. Следовательно, какого-либо влияния на работу программы это не оказывает.

Еще один способ написания комментариев — XML. Чтобы вставить его, программист должен перед тем, как вписать название класса, поля, свойства и прочего параметра, указать в коде тройной слеш «///».

Это способствует созданию в автоматическом режиме 2-х элементов:

• Summary. В данной строчке прописывается общий комментарий, в котором дается информация о том, для чего необходим метод и класс.
• Param. Здесь разработчик прописывает, какое значение необходимо передать.

Большинство инструментов, доступных для программистов, позволяют создавать подсказки. Они автоматически подгружаются к документам, которые касаются ПО. Несмотря на то, что многие могут расценить комментарии, как визуальные шумы, создание таких документов необходимо для дальнейшего использования программ.

Источник: synergy.ru

Пишем техническую документацию: руководство для непрофессионала

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

Исследование обнаружило некоторые альтернативные паттерны сканирования, такие как шаблон слоёного торта, пятнистая карта, шаблон разметки, шаблон обхода и целеустремлённый шаблон. Настоятельно рекомендую ознакомиться с докладом.

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

• В первых двух абзацах следует указать самую важную информацию
• Критически важны первые 3−5 слов
• Заголовки, абзацы и маркированные списки с информативными словами
• Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

Что такое документация API без кода, верно? Примеры кода есть во многих наших документах, и пользователи действительно их читают. Но проблема в том, что они не всегда обращают внимание на окружающий текст.

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

var client = new Keen(< projectId: «your_project_id», writeKey: «your_write_key» >); var ticketPurchase = < price: 50.00, user: < id: «020939382», age: 28 >, artist: < id: «19039», name: «Tycho» >> client.addEvent(«ticket_purchases», ticketPurchase);

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js , но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined . 🙁 Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

Это сразу проясняет, как установить библиотеку, внедрить её в свой код и что нужно заменить в образце кода перед его запуском.

Копипаст багов

Поскольку у нас в документации много примеров кода, успешный копипаст — довольно важное свойство. Вот два примера того, где это не соблюдается:

# Скопируйте и вставьте следующую команду $ gem install rails

Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:

bash: command not found: $

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $ . Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

«Хорошие программисты копируют, великие программисты вставляют»

Он сделал это намеренно? Мы никогда этого не узнаем. Тем не менее, это иллюстрация, как программисты пытаются выделить большие блоки текста на некоторых сайтах документации. Убедитесь, что пользовательский интерфейс сайта позволяет легко копировать большие блоки. Можно даже разбить эти блоки, чтобы объяснить фрагменты по отдельности.

Так они станут доступнее для копирования и понимания.

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию.

Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

Выбор слов действительно имеет значение. Эмпатия — это способность понимать и разделять чувства других. Когда мы проявляем эмпатию, то помогаем не только новичкам, но и более продвинутым пользователям. Это помогает увеличить потенциальное количество пользователей, вариантов использования, клиентов и даже доход компании.

Но когда документацию пишет эксперт-разработчик проекта, проявить эмпатию сложнее. Вот несколько полезных советов, которые помогли мне в прошлом:

• Попросите менее опытных участников проекта честно прокомментировать документацию
• Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
• Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
• В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
• Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

Обычно пользователи чаще видят сообщения об ошибках, чем документацию. Как говорит Кейт Восс, «сообщения об ошибках на самом деле представляют собой возможность». Я считаю, что многие разработчики документации упускают эту возможность. Здесь есть место для обучения, установления доверительных отношений и ожиданий пользователей. Прежде всего, вы поможете людям помочь самим себе.

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.

Гуманность

Используйте понятные человеку термины, избегайте фраз типа «исключение выброшено целевым объектом вызова». При написании кода, для которого вызывается много сообщений об ошибках, легко сбиться с понятной лексики.

Пример (ошибка кода состояния 401 у Twilio):

Полезность

Если вы запомните что-то из этих советов, запомните о полезности. Поделитесь с пользователем информацией, как устранить проблему.

Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 4000px по высоте и 4000px по ширине.

Как писать сообщения об ошибках

Как и в любой другой документации, сначала укажите важную информацию. Это можно сделать, указав сначала объект, затем действие. Пользователь ищет результат, а не как туда добраться. Это полезно, когда пользователи быстро сканируют сообщения об ошибках.

Нажмите кнопку «назад», чтобы вернуться на предыдущую страницу.

Чтобы вернуться на предыдущую страницу, используйте кнопку «назад».

Сообщения об ошибках в документации

Я считаю очень полезным, когда общие сообщения об ошибках API упоминаются в документации. Так автор документации может разъяснить сообщение об ошибке, не увеличивая документацию, в то же время помогая пользователю понять, почему возникает ошибка.

Twilio публикует полный каталог ошибок и предупреждений с возможными причинами и решениями. Используя этот метод, вы можете сделать фактические сообщения об ошибках короче, но по-прежнему полезными.

В случае ошибки 20003 (ошибка кода состояния 401, упомянутая ранее), есть много возможных причин, которые чётко изложены в каталоге.

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

Вы даже можете найти свои сообщения об ошибках в вопросах StackOverflow. Ответьте на них скромно, по-человечески и с пользой. Из-за SEO пользователи часто попадают с вашими сообщениями об ошибках на StackOverflow, а не в реальную документацию.

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.