Создание большой документации API: инструменты и методы

Ответ 1

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

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

Более распространенной формой пользователя документации по API является "человек, который просто хочет, чтобы все было сделано". Он (или она) имеет представление о том, чего они хотят достичь. У них также есть идея, где их найти, поэтому скажем, что они нашли вашу функцию. Здесь начинается проблема - они действительно не хотят читать документацию. Теперь предположим, что ваш вызов имеет пять параметров, четыре очевидных, но у одного есть предостережение (например, "отправлять только открытый сеанс" ). Если вы перейдете по списку параметров и полностью определите их, они будут устали и обезжирены и не заметят критической вещи. Я не могу это подчеркнуть - люди полностью не заметят того, что их смотрит в лицо. Это становится еще более сложным - если они считают, что они полностью понимают эту функцию, даже если они потрудились прочитать документацию, они, скорее всего, будут пропускать ее. Я видел, как люди пропускали очевидные оговорки в отношении методов с документацией с двумя предложениями.

Итак, вот что вы можете сделать:

• Предположим, что большинство пользователей фактически не прочитают документацию о функциях, которые они вызывают. На самом деле, чем более интуитивно понятен ваш API, тем меньше шансов, что кто-то прочитает документацию. Каждый читал бы функцию со странным именем и 20 параметрами. Но если вы напишете очень простой API с неприятным предостережением, вы рискуете, что его никогда не читают. единственное решение здесь (у меня есть для Java, но не для Интернета), чтобы избежать сюрпризов.

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

Наконец (и кредит здесь принадлежит Джеффу Стилосу, который также сделал свою кандидатуру на API): Предоставьте рецепты для определенных операций (даже как отдельную веб-страницу) и подумайте о создании "заполнителей" в тексте документации для методы, которые не являются частью API, но пользователи, возможно, захотят. Например, если многие пользователи захотят сделать Z, но способ сделать это в вашем API - это сделать X, а затем Y, добавить в документацию местозаместитель "do Z" и сказать им специально для вызова X и Y.

Ответ 2

Несколько методов документации, которые я усвоил:

• Синтаксические диаграммы (особенно железнодорожные диаграммы) обеспечивают очень четкий, читаемый способ описания синтаксиса команд и опций.
• Всегда предоставляйте хотя бы один пример для каждой используемой функции/концепции. Предпочтительно включать простое и сложное.
• Используйте стиль Inverted Pyramid - сначала укажите самую важную информацию, а затем постепенно менее важно!. позволяет пользователю выбирать, как далеко читать, основываясь на деталях, в которых они нуждаются. Также относится к общей документации - дайте концепции в первом разделе и сохраните точные детали до конца.
• Учебники или примеры необходимы, и они не должны быть ни тривиальными, ни слишком сложными!
• НЕ заставляйте своих пользователей изучать вашу собственную систему скобок, скобок, угловых кронштейнов и жирный/курсив/подчеркивание/интервал, чтобы прочитать вашу документацию. Да, вы должны иметь согласованную систему, но она должна следовать одной из общих конвенций или предпочтительно использовать синтаксические диаграммы, где это возможно.

Ответ 3

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

• Что это такое и почему вы можете его использовать.
• Как загрузить/купить, установить и настроить его
• Как начать с него (учебник)
• Как сделать с ним более сложные вещи (актуальные руководства)
• Документация API (автогенерация)

Эти разделы могут не публиковаться в одном и том же месте (они могут быть на отдельных веб-сайтах) или созданы с использованием тех же инструментов (wiki, auto-doc generator и т.д.), но каждый раздел должен быть напрямую доступен через ссылки из любой другой раздел (в верхней части каждого источника должно быть оглавление). Это позволяет вам использовать наиболее подходящий инструмент для каждого раздела документации и по-прежнему обращаться ко всем соответствующим областям.

Я думаю, что такой подход необходим, потому что:

• автоматически создаваемые документы не отстают от новейшего API, но бесполезны для новичков.
• wikis привлекает сообщество, но не может идти в ногу с частыми изменениями API.
• Файлы README слишком статичны

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

Ответ 4

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

Слой 1: самодокументирующий код Насколько это возможно, сделайте ваш API требуемым как можно меньше документации. Следуйте (и публикуйте) соглашения об именах для ваших функций, параметров и типов данных, которые делают их цель очевидной. Лучшая документация - это документация, которая не нужна.

Уровень 2: Пошаговые руководства/Пример кода Хотя многие люди не будут читать документацию по API, чтение через образец кода обычно считается менее болезненным (и некоторым, более полезным). Создайте простые, простые примеры, которые используют ваш API и публикуют их отдельно от ваших документов API. Покройте как можно больше общих сценариев использования. Хотя это не даст пользователям такой же степени знаний, как изучение API, это, по крайней мере, даст многим пользователям отправную точку. Даже если они просто вырезают и вставляют образец кода и используют его как скелет для своих собственных, они будут начинаться с известного рабочего кода, и вы уменьшите количество "новичков" вопросов и запросов поддержки, которые вы получаете.

Уровень 3: подробная, постоянно обновляемая документация Очень многие люди читают это или нет, всегда важно иметь подробный, исчерпывающий набор документации. Для этого я предпочитаю использовать генераторы документов, такие как Doxygen. Это особенно удобно, если у вас есть какой-то автоматизированный процесс сборки. Для нашего проекта у нас есть сервер, который ночной сборки, а также обновляет проектную документацию в ночное время. Таким образом, каждый может видеть самые современные документы, когда они просматривают их в Интернете.

Генераторы документов дают несколько преимуществ. Во-первых, легко поддерживать документацию в актуальном состоянии. Поскольку генераторы используют комментарии и обозначения в исходном коде для создания своего вывода, использование генераторов документов также побуждает разработчиков тщательно и надлежащим образом документировать свой код (таким образом, документация находится в исходном и внешнем документах, и вам нужно только написать его один раз). Если ваш проект содержит несколько веток или у вас есть разработчики, работающие с несколькими различными версиями вашего кода, генератор документов может создавать документацию для любой конкретной версии используемого исходного кода. Кроме того, автоматически созданная документация не требует дополнительных усилий для резервного копирования или архивирования (поскольку она может быть воссоздана из исходного кода, хранящегося в репозитории управления версиями, правильно?).

В моем опыте предоставление этих трех уровней документации дает наилучшие результаты. Те, кто хочет читать документы и изучать API, могут это сделать, а те, кто не справляется, могут получить достаточно хорошо, не делая этого. С вашей точки зрения, этот метод также требует минимальных усилий. Первый уровень - это то, что многие проекты программного обеспечения уже делают. Второй слой обычно поставляется в виде копий разделов кода, которые вы уже написали, упростили и опубликовали на веб-сайте или в wiki. На третьем уровне может потребоваться некоторая работа по переформатированию существующих комментариев, чтобы следовать соглашениям, ожидаемым вашим генератором документации; однако Doxygen (и, возможно, другие) может генерировать довольно приличный набор документов даже без добавления комментариев в формате Doxygen.

Ответ 5

Несколько вещей, которые следует учитывать:

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

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

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

Ответ 6

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

Что касается техник... Тот, который действительно работает для меня, выглядит следующим образом:

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

Надеюсь, это поможет.

Ответ 7

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

Нет, обычно из комментариев кода, используемых этими инструментами, не хватает подробных сведений. См. Ниже.

Вы легко и быстро находите инструменты на основе Wiki, чтобы поддерживать актуальную документацию по вашему API?

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

Были ли вы найдены какие-либо инструменты или методы, которые обеспечивают "лучшее из обоих миров" - автоматизацию и гибкость?

Шаблоны XML

Существуют ли какие-либо инструменты, упрощающие процесс документирования нескольких версий API?

Управление контролем источника. Darcs или Git среди других.

Какие инструменты и методы вы найдете наиболее полезными при создании отличной документации API?

Проще говоря: сделайте свою документацию по API самой кодовой.

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

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

Таким образом, мышление, которое должно быть выполнено, формируется из таких:

• Рассматривать документацию API как проект кода
• Кодеры должны иметь доступ к документу API "код" и делать ревизии так же легко, как если бы они были кодированием. Это означает, что он должен быть в текстовом файле, который можно редактировать в своем любимом редакторе/среде разработки.
• Кодеры используются для правильности синтаксиса и ограничений для компилятора/языка. Поэтому используйте систему шаблонов, которая требует и применяет определенные области содержимого. Основной XML - это начало.
• Храните сценарии перевода (XML в любом случае) в рамках проекта документации по API и поощряйте кодеры улучшать эти сценарии... то есть дать им что-то, с чем можно поиграть. (необязательно, но на самом деле помогает в конечном итоге улучшить документацию)
• Каждая функция API должна быть документирована в собственном исходном файле. Не помещайте более одного блока документации в один файл. Это позволяет сделать акцент простым и понятным для кодера, чтобы избежать увязнуть в "документации".
• Задавайте задачи, этапы и т.д., как обычный проект. Не документируйте документацию API, полностью содержащуюся в вашем основном проекте, который вы документируете. Это помогает дать обоснованность и сосредоточиться на выходе и помогает избежать его выравнивания или минимизации стороны - о, нам нужен всего один день, чтобы написать кашель документации. Очень проблема мышления, однако это может быть эффективный подход.

Одна из реализаций, которые я нашел хорошо работать, - это использование XSL-преобразований с использованием XML-шаблонов и входов CSS для создания XHTML-вывода. Очень просто видеть результаты и легко настраивать. Это также легко для дизайнера создать приятный макет/искать документацию, не касаясь самой документации.

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

Ответ 8

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

Uri Dekel (также здесь) подробно ответ в этой теме очень интересный, и я надеюсь, что его (и Джефф Стилос) диссертация будет скоро доступна где-то в Интернете.

В то же время посмотрите Проект API юзабилити @CMU, особенно на юзабилити подпроекта API eSOA (внизу на той же странице). Есть пара документов, подтверждающих мою гипотезу о том, что удобство использования API и удобство использования документации различаются:

• Пример использования API-редизайна для улучшения удобства использования;
• Улучшение документации для API eSOA с помощью пользовательских исследований.

Так лучше, что вы обращаете внимание на оба.

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

В CodeProject есть статья о удобстве использования API, которая, как представляется, хорошо информирована и написана.

Том Джонсон, старший технический писатель, имеет сообщение в блоге специально о Юзабилити документации.

И так далее.. простой веб-поиск с "API-интерфейс пользователя" и "веб-сервисы" дает гораздо больше материала, из которого можно выбрать.

P.S.: выбор подходящего инструмента для документации - это IMO, последняя из ваших забот.

Ответ 9

Резюме. Используйте компилятор для создания заглушек API из самой документации.
Предостережение: Не дешевое решение, но кто сказал, что сегодня вы можете бесплатно получить обед.
Советы. Используйте flex/bison для создания компилятора генерации заглушки API.

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

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

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

например. perf.api

#########################################################################
@arg1(string): Blah blah blah
@arg2(string): Blah blah blah
@perfcounter: Provides a cli interface to get back performance counter.
@return(int): perf counter value
#########################################################################

Compile:

> stubcc perf.api
  generated perf.h
  generated perf.c

Сгенерированный файл perf.c:

#include "perf.h"
int
perfcounter_stub(char *arg1, char *arg2)
{
    return perfcounter(arg1, arg2);
}

Сгенерированный файл perf.h:

#ifndef PERF_H
#define PERF_H

extern int perfcounter(char*, char*);

#endif

Разработчик реализует perfcounter() в отдельном файле.

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

Ответ 10

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

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

• Документ "View from 10,000 Feet", который объясняет структуру, функции и процессы, поддерживаемые вашим API. В этом заключается контекст для более подробной документации. Немногие пользователи на самом деле хотят прочитать все ваши мудрые слова, поэтому, когда они приходят вместе с вопросом "Как мне сделать X", вам нужно сообщить им "Посмотрите на компонент Y", чтобы они могли перейти к преследованию. Контекстный документ наиболее эффективен, если вы можете создать несколько диаграмм, чтобы сделать основную структуру (ы), которую люди могут визуализировать. Существует множество вариантов, но Wiki предоставляет средства для размещения любого такого документа таким образом, чтобы пользователи могли вносить свой вклад и знали, в каких областях они чувствуют потребность расширяется.

• Документ низкого уровня, который описывает каждый вызов, ответ, параметр и тип данных. Лучшей особенностью такой документации является обеспечение ее всестороннего сшивания и обновления. Когда я смотрю на данный вызов, я хочу иметь возможность ссылаться на каждый тип данных, каждый связанный вызов и любые другие детали API с помощью всего лишь щелчка мыши. На мой взгляд, автоматически созданная документация из комментариев в коде является идеальным механизмом для обеспечения этого, потому что:

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

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

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

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

Ответ 11

Какие инструменты и методы вы найдете наиболее полезными при создании отличной документации API?

Я не создал отличную документацию API, но я использовал некоторые.

Самый ценный инструмент и техника, с которыми я столкнулся, - это документация, включающая в себя полные примеры, которые на самом деле работают, и что пользователи могут взаимодействовать. Одним из самых ярких документов API, которые я когда-либо читал, является Inform 7 Designers 'Manual, который, кажется, разделился на два руководства, так как я последний раз прочитал. Ранний проект (2006) составлял около 700 страниц и содержал более 300 завершенных рабочих примеров, каждый из которых мог моментально загружаться и взаимодействовать. Это была удивительная помощь в изучении очень богатого и сложного API.

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

Ответ 12

Существует множество утилит, которые позволяют вам писать и поддерживать полную и обновленную документацию API. Конечно, вы можете легко найти их простым прохождением (doxygen, javadoc, rdoc и т.д.). Однако, как указывал Ури, людям просто нужно сжатие и точка зрения на использование пакета или API.

Думая, что писать и как писать, мне пришла в голову самая полезная помощь, которую я помню, получив. Большинство документации модуля perl имеют часть "СИНТАКСИС". Это настоящий стартер с библиотекой или API, который я не нашел неожиданно, скажем, в автоматически созданной документации API (например, в Qt или некоторых Java-пакетах, созданных javadoc). Учитывайте, что вы находите, когда говорите:

$ perldoc CGI

Вы знаете, чего ожидать, и вы найдете пример только до точки:

     # CGI script that creates a fill-out form
     # and echoes back its values.

     use CGI qw/:standard/;
     print header,
           start_html('A Simple Example'),
           h1('A Simple Example'),
           start_form,
           "What your name? ",textfield('name'),p,
           "What the combination?", p,
           checkbox_group(-name=>'words',
                          -values=>['eenie','meenie','minie','moe'],
                          -defaults=>['eenie','minie']), p,
           "What your favorite color? ",
           popup_menu(-name=>'color',
                      -values=>['red','green','blue','chartreuse']),p,
           submit,
           end_form,
           hr;

      if (param()) {
          my $name      = param('name');
          my $keywords  = join ', ',param('words');
          my $color     = param('color');
          print "Your name is",em(escapeHTML($name)),p,
                "The keywords are: ",em(escapeHTML($keywords)),p,
                "Your favorite color is ",em(escapeHTML($color)),
                hr;
      }

      print end_html;

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

Ответ 13

Самоочевидное именование в любых элементах API.

Четкая и краткая документация этих элементов.

Документация не должна создаваться в результате проектирования API, но на основе функциональных требований, указанных при инициации проекта.

Инструмент не имеет значения при обновлении документации.

Ответ 14

В настоящее время я использую построитель файлов подсказок Sandcastle.

Это инструмент для Windows, который может создавать документацию в стиле MSDN из комментариев документации XML, которые вы вставляете в исходный код .NET.

Этот автоматически созданный контент хорош, но недостаточно: вам также нужны вводные разделы, в которых представлено программное обеспечение в целом, скажем, как его установить, возможно, есть учебники для различных случаев использования и т.д. Вы можете использовать SHFB для автор этой информации тоже: SHFB называет это "концептуальным контентом", и вы пишете ее/отмечаете ее с помощью схемы "MAML".

Внутри концептуального контента, который вы пишете, вы можете легко кодировать гиперссылки на любую страницу справочной документации по API.

Кроме того, хотя содержание концептуального контента зависит от вас, оно отображается в HTML с использованием тех же таблиц стилей, что и ссылка на API: например, если страница справочной документации по API (созданная из комментариев в коде) выглядит как this, а страница концептуального контента (написанная с использованием MAML) выглядит как это.

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

Ответ 15

Генераторы документации отлично подходят для создания ссылок между частями документации и проверки макета и т.д., но они не могут добавить информацию, которая там отсутствует. Наиболее часто отсутствующая часть информации: "Зачем мне это нужно?"

В моем случае я использую два инструмента:

• Вики, чтобы дать вам общую картину. Что происходит, где и где искать детали. Этот материал редко меняется и просто рассказывает о дизайнерских решениях и дает указатели. Он легко редактируется, но в основном статический.

• Множество тестов, которые показывают, как вы можете использовать код. Вам все равно нужно написать их, так что напишите их так же, как и любой другой код (чистый и читаемый) и превратите их в свои примеры. Основные преимущества: Документация может лежать, ошибаться или быть устаревшей. Тесты всегда говорят правду (TATTT).

И всегда помните: точно так же, как строка кода, строка текста должна поддерживаться. Хуже того, строка текста не поставляется с компилятором, чтобы проверить ее. Поэтому держите документацию как можно короче (но не короче).