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

12

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

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

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

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

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


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

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

Дэн МакГрат
источник
Зачем вам нужно документировать язык? Это эзотерический или заказной язык? У него уже нет документации? И если нет, то почему вы выбрали его в первую очередь?
Яннис
@YannisRizos - я думаю, вы можете предположить, что это пользовательский скриптовый / макроязык, а не то, что они намереваются документировать C ++. Как правило, документы для такого языка являются источником синтаксического анализатора - поскольку разработчик языка часто является основным пользователем
Мартин Беккет
2
@DanMcGrath Ну да, знание аудитории и уровня / объема существующей документации повлияет на то, как я напишу справочное руководство. Это будет только для внутреннего использования?
Яннис
1
@Telastyn - Да, это публично. У нас есть гораздо больше, чем просто справочные руководства, но этот вопрос был конкретно по этому аспекту: rocketsoftware.com/u2/resources/technical-resources
Дэн МакГрат,
1
Взгляните на документы Lua, чтобы найти отличный пример хорошо написанного и целенаправленного справочного руководства. Знакомство с языком является задачей отдельной книги «Программирование на Lua». Разделение ответственности работает хорошо, по крайней мере, для меня.
Ямад

Ответы:

16

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

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

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

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

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

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

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

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

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

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

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


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

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

комар
источник
@DanMcGrath Еще один совет для процесса разработки документа: рассмотрите подход push-track-backout-repeat . 1) подтолкнуть технических писателей к более строгому процессу 2) отслеживать качество документации, одновременно нажимая 3) в случае ухудшения качества, вернуться к «более мягкому» процессу 4) через некоторое время - после того, как они привыкли к текущему уровню - повторить толчок к более строгому. И так далее, и так до тех пор, пока вы там не будете на 100%. :)
комнат
1
У меня есть одна болтовня. То, что вы описали, является учебником или набором учебников. Учебник не является справочным руководством. В руководстве описывается, как работает язык, а в справочном руководстве каталогизируются элементы языка. Важны и учебник, и справочное руководство, но они дополняют друг друга.
Гилберт Ле Блан
Вопрос @GilbertLeBlanc был о «справочном руководстве», которое я (и я думаю, что Википедия ) считает достаточно широким, чтобы охватить материал в моем ответе
комнат
5

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

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

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

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

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

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

Эли Розенкруфт
источник