Что такое Хорошая Онлайн-документация? [закрытый]

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

, Что, и это должно иметь хорошие поисковые средства.

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

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

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

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

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

пз: и обеспечение загружаемой версии для офлайнового использования всегда хорошо.

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

Это имеет большое значение при оценке библиотек. Я все еще не знаю что Adobe Adam& Канун действительно о.

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

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

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

Документация Django довольно удивительна ( http://docs.djangoproject.com/ ), его довольно всестороннее и легкое для чтения и делает это быстрым для нахождения то, в чем Вы нуждаетесь.

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

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

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

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

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

1. Быть ясным и краткий
2. А, хороший , пример стоит тысячу слов
3. Полезный , примеры (не то же как № 2)
4. Добавляют примеры из материала, который типичный пользователь / большая часть пользователя хотел бы, чтобы сделать, с чем Вы документируете.
5. я упомянул примеры ?

Специфические особенности: Я ненавижу то, что документы API Java не имеют фактически никаких примеров. Ищите практически любой класс или метод и nada, даже один лайнер. Не то, чтобы один лайнер достаточен в большинстве случаев, но они не могли даже быть побеспокоены этим.

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

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

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

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

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

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

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

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

я особенно недоволен предположением позади оператора в вопросе о томе страниц “1500-чего-то like” xpectation для хороших печатных версий. Мне это не хороший пример никакого вида документации за исключением энциклопедии.

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

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

Да, я являюсь достаточно взрослым для предпочтения страниц справочника Unix. Запустите с тех, и я возьму (или не) остальную часть его, когда и если я буду нуждаться или хотеть это.

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

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

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

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