Что такое хорошая онлайн-документация?

Ответ 1

Многие успешные проекты с открытым исходным кодом демонстрируют, как может выглядеть хорошая онлайн-документация.

Некоторые аспекты:

• Обновлено. Если документация не в актуальном состоянии, это может стать шоу-стоппер.
• Многие онлайн-документы начинаются с некоторый короткий учебник. Они показывают некоторые ключевые аспекты программного обеспечения и пользователь знает и заинтересован в копании глубже.
• Часто HowTos или часто задаваемые вопросы очень полезны. Многие пользователи предпочитают не читать и просто попробуйте. В какой-то момент пользователи, скорее всего, тот же вопрос снова и снова. Быть что пользователи могут запрашивать и о чем они уже просили.
• Для заинтересованных пользователей некоторые из них содержат подробную информацию в базовой документации.
• Также подумайте над аудиторию документации. Как автор документации, я думаю, ее очень полезно четко сформулировать какой аудиторией является документация за и какие знания они должно быть уже. Это заставляет меня быть конкретным и кратким. Сюда Я могу в конечном итоге отделить документации в разных частей, что делает документацию очень структурированный.

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

Самая сложная задача - обновить документацию. Напишите документацию с учетом будущих изменений.

Ответ 2

Множество минимальных образцов кода. Один за задание. Определите 5 лучших задач; Сделайте это без проблем, чтобы скопировать/вставить их реализацию из ваших документов и скомпилировать ее. Да, я вернусь и прочитаю фактические объяснения. Я хочу сначала увидеть мясо.

Это имеет большое значение при оценке библиотек. Я до сих пор не знаю, что такое Adobe Adam & Eve.

Ответ 3

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

• он должен быть FAST - как обычный просмотр, так и поиск
• он может быть связан, я хочу, чтобы иметь возможность отправить кому-то ссылку на определенную часть документации

В качестве отрицательного примера: http://livedocs.adobe.com всегда чувствует себя медленно и много времени, когда он не связан: - (

PS: и предоставление загружаемой версии для автономного использования всегда приятно.

Ответ 4

Хорошая документация должна объяснять "почему", а не просто "что". Почему я хочу использовать эту функцию? Какими сценариями это полезно?

Это, и у него должны быть хорошие средства поиска.

Ответ 5

Личная ненависть к питомцу: проекты, которые запускают doxygen поверх своих заголовков и считают, что документация завершена. Вам абсолютно необходим вводный материал... учебники, рабочие (желательно автономные) примеры кода, обзор, чтобы указать вас на наиболее важные классы в справочной документации. Qt является одним из лучших примеров этого, сделанного хорошо IMHO.

Кроме того, не забудьте предоставить достойный инструмент поиска (даже если вы перенаправляетесь на поисковый поиск по сайту). Это одна из причин, по которой я иногда предпочитаю файлы MSch.chm для размещения в онлайн-руководствах.

Ответ 6

Я думаю, что у PHP есть лучшая онлайн-документация для языка.

Если есть функция, которую я не знаю, для использования, я бы пошел на php.net/function-name.

Например, если я ищу функцию debug_backtrace, я бы посетил php.net/debug_backtrace. Если я неправильно сформулировал имя функции или ее не существует, сайт попытается найти правильную функцию и перенаправить вас туда. В противном случае он покажет вам поиск по функции PHP, которая ближе всего к функции, которую вы ищете.

Ответ 7

• Краткий текст (не требуется много чтения, тем самым меньше времени на чтение документов)
• Хорошие примеры
• Быстрый поиск того, что вы ищете (без необходимости поисковой системы, но как на большой странице индекса)

Ответ 8

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

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

Самые важные вещи:

• Будьте четкими и лаконичными
• Хороший пример стоит тысячи слов
• Полезные примеры (не то же самое, что и # 2)
• Добавьте примеры данных, которые типичный пользователь/большинство пользователей захочет/должен будет делать с тем, что вы документируете.
• Я упомянул примеры?

Особенности: Я ненавижу тот факт, что java API docs практически не имеет примеров. Посмотрите практически на любой класс или метод, а нада, даже на один лайнер. Не то, чтобы в большинстве случаев один лайнер был достаточным, но их даже не беспокоило.

Ответ 9

Что мне действительно не нравится, так это формат документов MSDN. Я предпочитаю стиль документации JAVA Sun, Flex 3 Livedocs (http://livedocs.adobe.com/flex/3/langref/) и PHP тоже.

Ответ 10

• Возможность отправлять комментарии полезна, так как это может захватывать документацию, написанную с другой точки зрения, или идеи, о которых вы не думали первоначально.
• Если у вас есть время, чтобы проверить изменения в вики-стиле документации, это также поможет получить аналогичные дивиденды.
• хороший инструмент поиска
• множество якорных точек #bookmark на длинных страницах, что позволяет легко ссылаться на разделы на таких сайтах
• используя гибкий формат, например DocBook, можно вручную отображать руководство, например HTML, PDF, CHM и т.д..

Ответ 11

Хорошая документация должна быть скиммой. Это должно быть написано с точки зрения того, что 90% ваших пользователей не захотят читать более 10% материала. Всегда существует разрыв между автором, который сосредоточен на написании чего-то хорошего и читателя, который просто хочет убрать вещи.

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

Ответ 12

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

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

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

То, что я ищу на документации, если у него есть те, то я куплю его;)

Ответ 13

Реальные примеры кода, а также минимальные.

Примеры Hello-world – отлично, но нам нужно знать все оговорки, которые следует принимать во внимание в производственном коде, т.е. последствия для безопасности, небезопасность потоков и т.д.

Ответ 14

Онлайн-документация (по крайней мере, каноническая стандартная версия) должна быть краткой и краткой. Но тогда каноническая версия всей документации должна быть короткой и краткой, поэтому для меня онлайн-документация просто должна дублировать канон.

Я особенно недоволен предположением, стоящим за выражением в вопросе о том, что "1500-тоеееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееееее Для меня это не хороший пример любой документации, не содержащей энциклопедии.

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

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

Да, я достаточно взрослый, чтобы предпочесть страницы man unix. Начните с тех, и я возьму (или не) оставшуюся часть, когда и если мне нужно или захочется.

Ответ 15

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

Бесплатно, например: screwturn