Онлайн-документация — руководства пользователя, ссылки на API, справочные центры, руководства по продуктам — может быть опубликована в формате PDF или в виде веб-страниц (HTML). Выбор формата влияет на то, как пользователи находят и читают контент, насколько легко его можно обновлять и хорошо ли он работает на мобильных устройствах. У каждого из них есть свои сильные стороны, и многие организации используют оба для разных целей.
Как лучше работает HTML-документация
HTML-документация является встроенной в Интернет. Поисковые системы индексируют отдельные страницы, а это означает, что пользователи, ищущие определенную тему, могут перейти непосредственно в соответствующий раздел, вместо того, чтобы загружать файл и искать в нем. Поиск в Google по запросу «как сбросить пароль вашего продукта»; может направить пользователя прямо на страницу 47 вашего справочного содержимого — что невозможно, если за ссылкой для скачивания стоит PDF.
HTML также адаптируется к любому экрану. Пользователи мобильных устройств могут читать документацию без масштабирования и прокрутки страницы с фиксированным макетом. Содержимое можно обновить без замены файла — исправьте опечатку или обновите снимок экрана, и изменения сразу же станут доступны всем пользователям. А HTML-документация может включать в себя интерактивные элементы: примеры кода, которые пользователи могут копировать одним щелчком мыши, расширяемые разделы, встроенные видео, живой поиск по всему содержимому.
Попробуйте отредактировать PDF
Никакой установки не требуется. Работает прямо в вашем браузере.
Где PDF документация имеет преимущество
Документация PDF работает в автономном режиме. Пользователь, загрузивший руководство, может прочитать его без доступа к Интернету — в самолете, в центре обработки данных с ограниченными возможностями подключения или при работе с оборудованием в средах, где использование телефонов запрещено. Для документации по аппаратному обеспечению, промышленных руководств или любого технического справочника, который используется в полевых условиях, это является значительным практическим преимуществом.
PDF также поддерживает фиксированный макет, который можно надежно распечатать. Когда техническому специалисту необходимо работать с распечатанным контрольным списком или руководством по установке, PDF, который каждый раз печатается правильно, лучше, чем HTML, который может непредсказуемо переформатироваться в разных браузерах и принтерах.
Для формальной документации, представляющей конкретную версию продукта — руководства для версии программного обеспечения 3.2, спецификации для конкретной версии продукта — PDF создает фиксированную запись, которая не изменяется. HTML-документация всегда актуальна, что обычно хорошо, но означает, что исторические версии документов не могут быть сохранены, если вы специально не версионируете их.
Обнаруживаемость: самый важный фактор
Для большинства онлайн-документации решающим фактором является возможность обнаружения. Если пользователям нужно искать помощь и находить ее через Google или поиск вашего сайта, HTML однозначно выигрывает. Содержимое PDF все чаще индексируется поисковыми системами, но не так детально — результат поиска, указывающий на конкретную страницу PDF, менее полезен, чем результат поиска, указывающий непосредственно на раздел HTML, который отвечает на вопрос.
Если вашу документацию в основном можно найти через навигацию (пользователи уже знают, куда идти), а не через поиск, разрыв в доступности не имеет значения, и в игру вступают другие факторы.
Общий гибридный подход
Многие группы документации публикуют оба формата. Основная документация существует в формате HTML — доступна для поиска, удобна для мобильных устройств и всегда актуальна. Экспорт PDF создается из того же содержимого для пользователей, которые хотят загрузить полное руководство, распечатать его или сохранить локальную копию. Такие инструменты, как Sphinx, MkDocs и GitBook, могут генерировать оба результата из одного и того же исходного контента с минимальными дополнительными усилиями.
Этот гибрид позволяет избежать компромиссов, связанных с выбором исключительно одного формата. Интернет-пользователи получают возможность поиска и адаптивный HTML-интерфейс. Пользователи, которым нужна офлайн-версия или версия для печати, получают чистый, хорошо отформатированный PDF. Содержимое хранится в одном месте и публикуется в обоих форматах, поэтому дополнительная нагрузка по обслуживанию не возникает.
Когда следует выбирать один вариант вместо другого
Выбирайте HTML, если: документация в основном используется в Интернете, важна видимость в поисковых системах, контент часто меняется или важен доступ с мобильных устройств. Выберите PDF, если: пользователям нужен автономный доступ, документацию необходимо распечатать, она представляет собой фиксированную версию продукта или ее необходимо распространять как отдельный файл. Для большинства современных программных продуктов и услуг HTML-документация с возможностью загрузки PDF эффективно охватывает обе основы.
Попробуйте отредактировать PDF
Никакой установки не требуется. Работает прямо в вашем браузере.