Использовать этот шаблон
Хорошая документация на ПО способствует внедрению, снижает нагрузку на поддержку и помогает разработчикам интегрироваться быстрее. С Trupeer вы можете сэкономить часы на написании документации, начав с бесплатного шаблона документации на ПО, настроив его с помощью ваших бренд-гайдлайнов и превращая длинные технические материалы в видеопошаговые обзоры, которые вовлекают любую аудиторию.
Что такое бесплатный шаблон документации на ПО?
Бесплатный шаблон документации на ПО — это повторно используемая структура для описания того, как работает конкретное ПО, для тех, кому нужно использовать, интегрировать, эксплуатировать или обслуживать его.
Фраза скрывает проблему, из-за которой чаще всего проваливается документация на ПО. Документация на ПО — это не один документ. Это минимум шесть документов, написанных для разных читателей с разными вопросами, и команда, которая берётся написать «документацию», в итоге создаёт нечто, что наполовину обслуживает всех сразу.
Шаблон — это не документация. То, будет ли она работать, определяется тем, знаете ли вы, какой из этих шести документов вы пишете, кто его читает и наблюдал ли кто-нибудь, как этот человек пытается им воспользоваться.
Формат следует типу. Бесплатный шаблон документации на ПО в Word подходит для дизайн-документов, спецификаций и всего, что проходит проверку и утверждение. Справочная документация должна находиться в системе документации или генерироваться из кода, а не существовать как отдельный документ. Бесплатный шаблон документации на ПО в PDF подходит для версионируемого результата, который вы передаёте клиенту. Бесплатный шаблон документации на ПО в Excel версии подходит для инвентаризаций и матриц трассируемости, а не для прозы.
Документация на ПО — это шесть документов, а не один
Разложено по читателю, потому что читатель определяет всё остальное.
Начало работы. Для того, у кого пока ничего нет и кому нужно, чтобы хоть что-то заработало. Читайте от начала до конца один раз. Самый короткий документ, который вы напишете, и именно он решает, будут ли вообще читать остальные.
Справка. Для того, кто интегрирует и должен понимать, что делает конкретная конечная точка, функция или настройка. Никогда не читайте линейно — всегда ищите. Полнота важнее, чем стиль. Часто генерируется.
Руководства и how-to. Для того, у кого есть конкретная задача. Организовано по тому, чего они пытаются достичь, а не по функциям — это различие описано на странице quick reference guide.
Архитектура и дизайн. Для того, кто поддерживает или расширяет систему, часто спустя годы. Единственный документ, чья главная ценность — объяснить «почему», а не «что», потому что «что» находится в коде, а «почему» — в чьей-то памяти.
Операционная документация. Для того, кто её запускает. Развёртывание, конфигурация, мониторинг и что делать, когда всё ломается. runbook описывает исполняемую часть этого.
Заметки к релизу и changelog. Для всех. Самая дешёвая документация в написании и чаще всего игнорируемая.
Поэтому лучший бесплатный шаблон документации на ПО — это тот, который соответствует типу документа, который вы пишете. Два из них читают, а четыре — ищут, это практическое разделение. Начало работы и архитектуру читают. Справку, руководства, операционную документацию и заметки к релизу вводят по мере необходимости.
Попытка обслужить два из этих типов одним документом приводит к характерному провалу: страница слишком подробная, чтобы с неё начать, и слишком повествовательная, чтобы в ней можно было что-то найти.
Как настроить этот шаблон в Trupeer
Шаг 1: Откройте раздел Templates
Перейдите в раздел Templates из главного меню.
Шаг 2: Выберите и откройте шаблон
Нажмите на любой шаблон, с которым хотите работать, чтобы открыть его.
Шаг 3: Разверните просмотр шаблона
При необходимости разверните просмотр шаблона, чтобы увидеть полную раскладку и детали.
Шаг 4: Отредактируйте шаблон
Нажмите Edit, чтобы начать изменять выбранный шаблон.
В редакторе вы можете:
Добавлять новые разделы
Задавать или обновлять правила форматирования
Добавить логотип и настроить его положение и связанные параметры
Шаг 5: Сохраните настроенный шаблон
После того как вы внесёте все необходимые изменения, нажмите Save, чтобы сохранить обновлённый шаблон как свой.
Шаг 6: Предпросмотр и точная настройка шаблона
Когда вы захотите увидеть, как выглядит ваш настроенный шаблон, откройте Preview.
На экране предпросмотра при необходимости вы можете продолжить вносить изменения напрямую, чтобы шаблон выглядел ровно так, как вам нужно.
С шаблоном документации на ПО вы можете:
Экономить часы на написании: пропускайте пустую страницу со структурой, созданной для документации на ПО.
Охватить любую аудиторию: разделы для конечных пользователей, администраторов, разработчиков и команд поддержки.
Оставаться в фирменном стиле: применяйте логотип, шрифты и цвета с помощью бренд-набора Trupeer.
Снижать нагрузку на поддержку: понятная документация помогает пользователям и разработчикам решать вопросы самостоятельно.
Легко обновлять: отредактируйте один раз — Trupeer автоматически сгенерирует видео.
Достигать глобальных пользователей: переводите документацию на ПО на 65+ языков одним кликом.
Единственный тест: время до первого успеха
Вот измерение, которое почти ни одна команда не делает, и оно стоит полдня.
Найдите трёх людей, которые представляют вашу аудиторию, и убедитесь, что они не пользовались ПО. Дайте им документацию и заранее определите первый результат: пусть они сделают успешный один API-вызов, развернут один экземпляр, завершат один рабочий процесс. Наблюдайте за ними молча и фиксируйте время.
Не помогайте. Желание помочь бывает непреодолимым, и любое вмешательство разрушает данные. Запишите, где они колебались, что открывали, что искали и точный момент, когда они сдавались.
Из этого надёжно получается три вещи.
Само число — обычно в несколько раз больше, чем ожидала команда, и это показатель, который нужно улучшать.
Место потери времени — почти всегда оно сосредоточено. В большинстве тестов большая часть потраченного времени уходит на один-два препятствия, и они редко оказываются теми, которые команда предполагала.
И характер препятствия — обычно то, о чём никто не подумал задокументировать, потому что это не часть ПО. Ключ, который нужно запросить. Разрешение, которое нужно выдать. Неверный дефолт. Институциональные знания, которые стали невидимыми для всех, кто их держит.
Справочную документацию таким образом проверить нельзя, потому что её вводят, а не читают. Проверьте иначе: возьмите десять самых частых вопросов в поддержку и засеките, сколько времени нужно, чтобы найти каждый ответ в документах. Всё, что дольше тридцати секунд, — это находка.
Что должен содержать шаблон документации на ПО
Компоненты для документа «Начало работы», потому что именно он решает, будет ли читаться что-либо ещё.
Компонент | Что он делает |
|---|---|
Для кого это и что предполагается | Формулируется прямо. Предполагаемые знания, которые не проговариваются, — самая частая причина того, что читатель застревает. |
Что у вас будет в конце | Первый успех, описанный конкретно, чтобы читатель понимал, к чему он движется. |
Предварительные условия | Всё, что нужно до шага один, включая всё, что требует запроса другому человеку, и сколько это занимает. |
Пронумерованные шаги к одному рабочему результату | Один путь. Не варианты, не альтернативы — один путь, который работает. |
Рабочий пример, который можно скопировать | Реальные значения, а не плейсхолдеры в угловых скобках. |
Как выглядит успех на каждом шаге | Что увидит читатель, чтобы он мог понять, продолжать ли дальше. |
Что делать, если не получилось | Три или четыре самых частых сбоя и их исправления — из ваших собственных тикетов поддержки. |
Куда идти дальше | Одна-две ссылки, выбранные, а не список всего подряд. |
Версия и дата последней проверки | Когда кто-то в последний раз выполнял эти шаги и подтвердил, что всё работает. |
Строка с предварительными условиями — та, которая «ловит» больше всего команд. Всё, что требует, чтобы человек выдал что-то, невидимо для тех, у кого это уже есть, и это единственное самое частое место, где новый читатель зависает.
Бесплатный шаблон документации на ПО: структура, которую нужно копировать
Заполнено реальным примером, а не плейсхолдерами. Это документ «Начало работы» для логистического API.
Скопируйте отсюда.
Для кого это. Для разработчика, который интегрирует отслеживание отправлений в существующую систему. Предполагается, что вы умеете делать HTTP-запросы и разбирать JSON. Предполагается, что у вас нет предварительных знаний о нашей платформе.
Что у вас будет в конце. Один успешный вызов, который возвращает данные живого отслеживания для тестовой отправки, примерно за пятнадцать минут.
Предварительные условия. Ключ песочницы, который вы генерируете сами в developer portal примерно за тридцать секунд. Согласование не требуется и нам не нужно отправлять email. Ссылка на отправление, для которой вы можете использовать тестовую ссылку, предоставленную в шаге три.
Шаги.
Сгенерируйте ключ песочницы в developer portal. Вы должны увидеть ключ, начинающийся с
sk_test_. Если вы видите ключ, начинающийся сsk_live_, значит вы в production portal, где требуется подписанный договор.Сохраните ключ как переменную окружения. Не добавляйте его в систему контроля исходного кода.
Сделайте ваш первый вызов, используя копируемый пример ниже, заменив только ваш ключ. Ссылка на тестовую отправку уже включена.
Вы должны получить ответ со статусом двести и телом JSON, содержащим поле status со значением
in_transit. Если вы получаете four zero one, ваш ключ не был выбран из окружения — это самая частая причина.Измените ссылку на отправление на любую другую тестовую ссылку со страницы тестовых данных и повторите.
Рабочий пример. Реальные значения, можно копировать, заменён только ключ.
Частые сбои. Четыре, взятые из наших тикетов поддержки, а не придуманные. Four zero one — почти всегда означает, что ключ не читается из окружения. Four zero three — это когда используется live-ключ с endpoint песочницы. Four zero four для корректной ссылки — это значит, что данные песочницы сбрасываются каждую ночь и вы используете ссылку вчерашнего дня. Timeout — это когда вы вызываете региональный endpoint за пределами этого региона.
Куда идти дальше. Только две ссылки. Руководство по отслеживанию, если вам нужны webhooks вместо опроса. Полная справка, если вы уже знаете, какая конечная точка вам нужна.
Версия и последняя проверка. Версия 4: шаги выполнялись end to end в последний раз 3 июня разработчиком, который видел их впервые.
Скопируйте сюда.
Эта последняя строка стоит того, чтобы применять её в целом. Страница документации с датой, когда кто-то действительно следовал ей, гораздо надёжнее, чем страница с датой, когда кто-то её отредактировал.
Пример документации на ПО: триста сорок страниц и три часа
Portwood Systems — компания примерно из девяноста человек, которая продаёт логистический API диспетчерам грузоперевозок — имела документацию, которой все тихо гордились.
Триста сорок страниц справочных материалов, сгенерированных из кода, полные и точные. Каждый endpoint, каждый параметр, каждый код ответа. Это было осознанное вложение, и справочная документация действительно была хорошей.
Тикеты поддержки от клиентов, которые всё ещё интегрировали, составляли около сорока процентов всех тикетов.
В какой-то момент кто-то запустил тест. Три разработчика на площадках клиентов, ни один из которых не использовал API, каждый попросил сделать один успешный вызов, пока сотрудник команды Portwood наблюдал и не говорил ни слова.
Внутреннее ожидание команды было двадцать минут.
Первый потратил три часа десять минут. Второй сдался через два часа и написал в поддержку по email. Третий потратил час пятьдесят.
Все трое потеряли больше сорока минут в одном и том же месте, и это было не в API.
Для аутентификации нужен был ключ песочницы. Ключи песочницы выдавались по email на адрес поддержки, с обработкой примерно за два дня. В документации это нигде не было указано. Справка точно описывала формат заголовка аутентификации, и нигде не говорилось, что ключ нужно получить — тем более как.
У каждого человека в Portwood уже был ключ. Несколько человек никогда не нуждались в том, чтобы запросить его. Этот шаг стал невидимым «изнутри», и так происходит с предварительными условиями в любой организации, если дать этому достаточно времени.
Триста сорок страниц были полными как справка и не содержали пути от «ничего» к «одному рабочему вызову». Справка отвечает на вопрос «что делает этот endpoint». Никто не написал ничего, отвечающего на «у меня нет ничего, как мне заставить это работать один раз».
Исправление заняло одну страницу и небольшой кусок инженерной работы. Шесть шагов: генерация ключа самообслуживания вместо запроса по email, один копируемый пример с реальными значениями и четыре частых сбоя, взятые из истории тикетов.
Перепроверили с тремя другими разработчиками: четырнадцать минут, двадцать две минуты, восемнадцать минут.
Тикеты поддержки по интеграции снизились примерно на шестьдесят два процента в течение следующего квартала. Медианное время от подписания договора до первого production-вызова клиента сократилось с тридцати одного дня до девяти.
С тремястами сорока страницами всё было в порядке. Просто никогда не было первой страницы.
Как писать документацию на ПО за шесть шагов
Определите, какой из шести документов вы пишете, и напишите его в одном месте. Документ, который обслуживает двух читателей, не обслуживает ни одного.
Назовите читателя и то, что вы предполагаете, что он знает. В тексте, в самом начале. Именно это делает предполагаемые знания видимыми для автора.
Сначала напишите документ «Начало работы», даже если он самый короткий. Он определяет, будет ли читаться что-либо ещё.
Перечислите предварительные условия, включая всё, что требует другого человека. Затем уберите как можно больше из них — насколько это может сделать инженерия, потому что каждый такой пункт — это точка остановки, измеряемая днями, а не минутами.
Берите сценарии сбоев из тикетов поддержки, а не из воображения. Ваши десять самых частых тикетов — это ваш бэклог документации, уже расставленный по приоритетам.
Проверьте это, наблюдая за человеком, молча. Всё выше — догадки, пока у вас не появится число.
Шаг шестой — это весь метод. Остальные пять — это то, как вы реагируете на то, что он вам говорит.
Как поддерживать актуальность документации на ПО
Документация ломается тихо. Никто не предупреждает вас, и человек, который это обнаруживает, обычно оказывается клиентом.
Работают три механизма, в порядке возрастания надёжности.
Даты верификации. Записывайте, когда кто-то в последний раз следовал шагам, а не когда страница была отредактирована. Дата редактирования говорит о том, что кто-то изменил слово. Дата верификации говорит о том, что это работало.
Привязывайте обновления к релизам, а не к календарю. Ежеквартальный обзор документации находит проблемы до трёх месяцев после их появления. Элемент документации в чек-листе релиза находит их до того, как они выйдут в прод — это аргумент, который приводится на странице release requirements, где документация должна находиться среди требований к блокирующей готовности, а не среди необязательных.
Генерируйте то, что можно сгенерировать. Справочная документация, созданная из кода, не может от него «уплыть». Поэтому справочная документация обычно самая точная и наименее полезная часть набора документации, а ошибки живут в тех частях, которые пишут люди.
Те части, которые нельзя сгенерировать, требуют самого пристального внимания: начало работы, руководства и всё, что содержит скриншот. Эти части ещё и быстрее всего деградируют, потому что интерфейсы меняются чаще, чем API.
Документация на ПО или документация проекта?
Их ищут вместе, и это разные вещи.
Документация на ПО описывает ПО: как оно работает, как им пользоваться, как его эксплуатировать. Её читатели — пользователи, интеграторы и инженеры, и она переживает проект, который её создал.
Документация проекта описывает проект: область работ, план, решения, риски, статус, согласования. Её читатели — стейкхолдеры и аудиторы, и она в основном завершена, когда проект завершён. Шаблон документации проекта Word free download даст вам уставы, отчёты о статусе и журналы решений — это полезно, но это не документация на ПО. project documentation template покрывает эту сторону.
Эти два типа путают при передаче, когда проект заканчивается и кому-то нужно продолжать запускать то, что было построено. Для этого перехода нужна именно документация на ПО, и типичная ошибка — передать полный архив проекта, не содержащий вообще никакой операционной документации.
Что бесплатный шаблон документации на ПО не может исправить
Не знать, кто это читает. Любое структурное решение следует из читателя, и ни один бесплатный шаблон документации на ПО free download не скажет вам, кто ваш читатель.
Предварительные условия, которые никто не видит. Проблема Portwood. Только наблюдение за человеком со стороны раскрывает эти вещи, потому что все внутри уже их прошли и забыли.
Документация, написанная тем, у кого есть время. Человек с ресурсом часто оказывается самым далёким от работы. Документация, написанная тем, кто не выполняет задачу, опишет предполагаемую последовательность, а не фактическую.
Продукт, которому нужно столько объяснений. Иногда проблема документации — это проблема продукта. Если начало работы действительно требует сорока шагов, это стоит поднять с тем, кто отвечает за продукт, даже если документацию всё равно нужно написать.
Показывайте ПО, а не описывайте его
Документация на ПО — это категория, где разрыв между «описать» и «показать» самый широкий, а стоимость поддержки закрытия этого разрыва — самая высокая.
Написать шаг, сделать скриншот, обрезать и подписать его, разместить правильно, а затем повторить всё это снова, когда меняется интерфейс — вот почему большая часть документации на ПО, которая должна быть визуальной, превращается в текст с одним скриншотом вверху. Интерфейсы меняются раз в несколько недель. Скриншоты — нет.
Trupeer AI убирает эту стоимость. Кто-то выполняет задачу один раз, записывая процесс, а результат — это письменный пошаговый обзор со скриншотами, которые уже сняты и размещены, вместе с видео, в вашем собственном фирменном стиле. Письменная версия становится руководством. Видео — это то, что смотрит новый пользователь перед попыткой, а именно этот материал сокращает время до первого успеха.
Запишите. Оформите в бренде. Переведите. Trupeer it.
За этим следуют три вещи, которые особенно важны именно для ПО. Перезапись после изменения интерфейса быстрее, чем переснятие скриншотов, поэтому визуальную документацию действительно можно поддерживать, а не бросать. Одна и та же запись даёт один и тот же пошаговый обзор на каждом языке, который вы поддерживаете, поэтому международные пользователи не работают с более старой версией истины. И запись делает человек, который выполняет задачу — это исправление для документации, написанной тем, у кого было время.
Материал находится в вашем knowledge base и одновременно служит обучением для поддержки и онбординга. Детальная операционная информация по задачам относится в work instructions. Единообразие между вашими документами — это вопрос один раз настроить brand kit, а настройка описана в document template setup guide.
Часто задаваемые вопросы
Есть ли бесплатный шаблон документации на ПО в версии Word?
Word подходит для типов документации, которые проходят проверку и утверждение: дизайн-документы, записи по архитектуре, спецификации и всё, что передаётся по договору. Файл Word шаблона документации на ПО хорошо работает для этих случаев.
Но он плохо подходит для документации, которую читают пользователи. Руководства и справочные материалы должны быть доступными для поиска, иметь ссылки и обновляться несколькими людьми — это система документации, а не один документ. Если ваше руководство пользователя — это Word-файл, который отправляют клиентам по email, ожидайте, что в обращении будет несколько версий в течение года.
Есть ли бесплатный шаблон документации на ПО в версии Word doc?
Да, и бесплатный файл Word doc шаблона документации на ПО — это то же самое, что Word-файл с более старым расширением. Важен не формат, а то, какой из шести типов документов вы создаёте.
Для дизайн- и архитектурных документов документ подходит. Для всего, что читает пользователь или интегратор, публикуйте, а не отправляйте, чтобы была одна актуальная версия, а не по одной для каждого получателя.
Есть ли бесплатный шаблон документации на ПО в формате PDF?
PDF подходит для версионируемого результата: документация, которую передают клиенту на релизе, прикладывается к договору или архивируется относительно регламентированной версии продукта.
Не используйте его для всего, что пользователи регулярно читают. PDF-файлы нельзя нормально искать по страницам так, как это делается на сайте документации, они не аккуратно связываются ссылками, и клиент, у которого есть PDF, не может знать, что существует более новая версия. Публикуйте актуальную версию и экспортируйте бесплатный шаблон документации на ПО в PDF только там, где действительно нужен зафиксированный документ.
Есть ли бесплатный шаблон документации на ПО в версии Excel?
Excel подходит для инвентаризаций, а не для прозы. Бесплатный файл шаблона документации на ПО в Excel подходит для матрицы покрытия документации, матрицы трассируемости, связывающей требования с тестами, инвентаря endpoint’ов API или списка того, что существует, и когда это было в последний раз проверено.
Этот последний сценарий действительно ценен и встречается редко. Одна строка на документ с его типом, владельцем, читателем и датой последней проверки расскажет о состоянии вашей документации больше, чем чтение любого из документов.
Есть ли бесплатный шаблон документации на ПО free download, который стоит использовать?
Список разделов занимает двадцать минут на сборку, поэтому бесплатный шаблон документации на ПО free download экономит совсем немного, а большая часть того, что публикуется, — это универсальный скелет документа, а не что-то конкретное для ПО.
Если вы используете один из них, проверьте, различает ли он типы документов. Почти никто этого не делает, а это различие — первое решение, которое нужно принять. Шаблон, который предлагает одну структуру для всей документации на ПО, предлагает ровно ту ошибку, против которой выступает эта страница.
Где можно получить шаблон документации проекта Word free download?
Это другой документ. Документация проекта описывает проект: устав, область работ, план, журнал рисков, запись решений, отчёты о статусе и согласования. Документация на ПО описывает ПО и переживает проект.
Шаблон документации проекта Word free download даст вам первое. Если вы на финише сборки и думаете, что передать, вам нужны оба, и операционная документация — это та половина, которая чаще всего отсутствует в архиве проекта.
Какой лучший бесплатный шаблон документации на ПО?
Лучший бесплатный шаблон документации на ПО — это тот, который соответствует конкретному документу, который вы пишете. Это означает заранее решить, создаёте ли вы начало работы, справку, руководство, архитектурную документацию, операционную документацию или заметки к релизу, прежде чем выбирать что-либо.
Если вы хотите один тест, чтобы сравнить варианты, посмотрите, спрашивает ли шаблон, кто читатель и какие знания предполагаются. Эти два поля делают для готового документа больше, чем любое количество структуры разделов.
Какой должна быть длина документации на ПО?
Начало работы должно быть на одной странице, и если это невозможно, то исправлять нужно предварительные условия, а не текст.
Всё остальное должно быть такой длины, как само ПО. Справочная документация для большой API — это вполне законные сотни страниц, и это нормально, потому что никто не читает её линейно. Ошибка — судить набор документации по общей длине, потому что это ничего не говорит. Судите по тому, сколько времени нужно новичку, чтобы добраться до первого успеха.
