Документирование языка программирования: Справочное руководство

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

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

Какие ключевые аспекты для каждого ключевого слова задокументированы?

• Синтаксис
• Описание
• Аргументы - если применимо
• Возвращаемые значения - если применимо
• Пример использования?
• Я скучаю по другим?

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

_{Это для внешнего потребления. У нас уже есть полные комплекты документов (см .: http://www.rocketsoftware.com/u2/resources/technical-resources ). Понимание того, что мы должны делать иначе - у меня уже есть свои идеи, но, как всегда, я стараюсь не полагаться исключительно на свое мнение.}

_{Аудитория: Технические разработчики, использующие наши базы данных и инструменты для производства программного обеспечения во многих отраслях.}

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

В вашем случае основной аудиторией, по-видимому, являются разработчики программного обеспечения. Части, которые необходимо рассмотреть здесь, направлены на то, чтобы адресовать разные «под-аудитории» этой:

1. Привет мир.
   Те, кто хочет быстро почувствовать это, просто создают и запускают пример приложения, чтобы посмотреть, как оно выглядит.
   Думайте об аудитории как о том, к которому обращается MySQL «правило 15 минут» :
   

   _{... пользователю, чтобы иметь возможность запустить MySQL через 15 минут после того, как он закончил загрузку.}

2. Основы.
   Для ребят, желающих быстро освоить вещи, необходимые для начала работы над рабочим программным обеспечением.
3. Расширенные темы.
   Для разработчиков уже хорошо знакомы и практиковались с основами, интересно узнать, что там за пределами. Основные темы, которые не были рассмотрены в Основах .
4. Руководство по стилю / Рекомендуемые практики.
   Субъективные советы и рекомендации для тех, кто интересуется тем, как вы рекомендуете делать вещи.
   _{Вопрос не указывает, может ли это иметь значительную аудиторию в вашем случае, поэтому варианты, которые следует рассмотреть, это включить его в качестве части / приложения к расширенным темам или даже полностью его исключить.}
5. Причуды.
   Темные темы, не относящиеся к мейнстриму, которые могут представлять интерес для довольно ограниченной части вашей аудитории. Например, если у вас есть устаревшая линия или такие вещи, как обновление / миграция / совместимость с устаревшей версией - поместите ее здесь. Если есть какие-то побочные эффекты для какой-либо функции в определенной «экзотической» среде, то речь пойдет об этом.

^{Что если что-то в руководстве сомнительно / неоднозначно? Что если окажется, что подробное объяснение отдельных понятий сделает это руководство слишком трудным для чтения? Что если окажется, что в данной версии руководства есть ошибки?}

Две вещи, которые следует учитывать для сопровождающих:

1. Техническая / формальная спецификация.
   Всякий раз, когда в руководстве есть сомнительная / неоднозначная / трудная для объяснения тема, читатель может обратиться к конкретному абзацу в спецификации, чтобы получить строгое и четкое «официальное» заявление по этому вопросу. Строгое и полное (и, скорее всего, скучное) описание синтаксиса языка было бы лучше пойти туда.
   Первостепенными соображениями для Спецификации являются техническая точность и полнота, даже если они идут за счет читабельности.
2. Онлайн приложение.
   Просто зарезервируйте какой-нибудь URL и поместите его в начале каждого выпускаемого вами документа, чтобы ребята, задаваясь вопросом, какого чёрта они только что прочитали, могли пойти туда (вместо того, чтобы приставать к ручным сопровождающим) и найти объяснение ошибки.

   _{Ошибки> Основы> Выпуск 2.2> Опечатка на странице 28, второе предложение начинается с удачи , вместо этого прочитайте блокировку .}

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

_{Было бы полезно организовать сравнительное изучение справочной документации для других языков, таких как ваш. Цель этого исследования - использовать опыт, полученный теми, кто делал это раньше, и научиться избегать допущенных ошибок.}

_{И последнее, но не менее важное: рассмотрите возможность настройки разработки документации, аналогичной разработке программного обеспечения. Я имею в виду такие вещи, как контроль версий, регулярные выпуски, отслеживание проблем, обеспечение качества и т. Д. Возможно, вы захотите пойти на некоторые компромиссы, хотя, если окажется, что ваши технические писатели не очень довольны такими вещами. Мы не хотим получать дрянной контент "в обмен" на идеальный процесс разработки, не так ли?}

Первое, что вам нужно сделать, это оценить аудиторию. Является ли ваша аудитория хакерами ядра Linux или разработчиками аппаратного обеспечения, которые используют программные инструменты для выполнения работы, но не интересуются программным обеспечением как таковым и не имеют опыта работы с CS. Инженеры-электрики, вероятно, не совсем понимают разницу между константными и неконстантными аргументами, указателями на объекты по сравнению со ссылками и т. Д. Если ваши примитивы имеют перегруженные имена, то вам лучше объяснить эту концепцию на соответствующем уровне для вашей аудитории, что может быть ничто, если они программисты C ++.

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

Не забудьте включить объяснение любых побочных эффектов ваших функций.

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

Традиционно технические писатели различают справочные руководства и руководства пользователя . Справочное руководство обычно включает в себя спецификации синтаксиса, понятное определение функций или примитивов, обсуждение полученных ошибок, производительности и побочных эффектов, а также краткий пример использования. Руководство пользователя содержит более подробные примеры использования и обсуждение более широких технических вопросов. Kernigan и Ritchie "C Programming Language" являются отличным контрпримером к этому соглашению, но этот подход работает только тогда, когда язык, который вы документируете, является относительно простым.

Автор был менеджером отдела инженерных услуг в центре разработки Ready Systems Inc с 1987 по 1991 год, отвечая за управление командой из пяти технических писателей.