Організуйте документацію відповідно до потреб цільової аудиторії.
У вашому випадку первинна аудиторія - це, мабуть, розробники програмного забезпечення. Розглянемо тут частини, які стосуються різних "під аудиторій" цього:
- Привіт Світ.
Ті, хто бажає швидко отримати смак, просто створити та запустити зразок програми, щоб побачити, як це виглядає.
Подумайте про аудиторію, як та, до якої звернулося MySQL "Правило 15 хвилин" :
... користувач зможе запустити MySQL і запустити його через 15 хвилин після закінчення завантаження.
- Основи.
Для хлопців, які бажають швидко засвоїти речі, необхідні, щоб почати виробляти робоче програмне забезпечення.
- Розширені теми.
Для розробників, які вже добре знайомі та практикують основи, зацікавлені знати, що є за її межами. Основні теми, які не були висвітлені в Основах .
- Посібник зі стилів / Рекомендовані практики.
Суб’єктивні поради та рекомендації для тих, хто цікавиться способом, як ти рекомендуєш робити справи.
Питання не вказує, чи може це мати значну аудиторію у вашій справі, тому можливим є врахування того, щоб включити його як частину / додаток до розширених тем або навіть повністю залишити його.
- Примхи.
Неясні теми, поза мейнстрімом, які можуть зацікавити досить обмежену частину вашої аудиторії. Наприклад, якщо у вас є застаріла лінія, або такі речі, як оновлення / міграція / сумісність зі спадщиною - поставте її тут. Якщо в певній "екзотичній" середовищі є деякі побічні ефекти для деяких функцій, це стосується цієї частини.
Ваша вторинна аудиторія - це керівники посібника. Ці хлопці можуть змусити або зламати те, як все працює для вашої основної аудиторії, тому вам краще подбати про їхні потреби та проблеми.
Що робити, якщо щось у посібнику сумнівне / неоднозначне? Що робити, якщо виявиться, що ретельне пояснення конкретних понять зробить цей посібник занадто важким для читання? Що робити, якщо виявиться, що конкретна версія посібника має помилки?
Дві речі, які слід врахувати для обслуговуючого персоналу, це:
- Технічна / формальна специфікація.
Щоразу, коли в посібнику є сумнівна / неоднозначна / важка для пояснення тема, читача можуть бути направлені до конкретного пункту в специфікації для чіткого і чіткого «офіційного» твердження з цього приводу. Точний і повний (і, швидше за все, нудний) опис синтаксису мови краще проходитиме туди.
Першочергові міркування щодо специфікації є технічна точність та повнота, навіть якщо вони виходять за рахунок читабельності.
- Інтернет-добавка.
Просто зарезервуйте якусь URL-адресу та покладіть її на початку кожного документа, який ви опублікуєте, щоб хлопці цікавились, що чорт, який вони щойно прочитали, змогли зайти туди (замість того, щоб домагатися технічного обслуговування керівників) та знайти помилку.
Errata> Основи> Випуск 2.2> Друкарська помилка на сторінці 28, друге речення починається з удачі , замість цього читайте блокування .
Такі поняття, як стратегії блокування, деталі, що стосуються продуктивності, повинні бути включені (можливо частково) там, де, як ви очікуєте, потрібна цільовій аудиторії.
Наприклад, керівники технічного обслуговування, очевидно, зацікавлені в повному, точному описі одночасності та фіксації у формальній специфікації - розмістіть її там. Читачів фундаментальних чи додаткових тем може бути зацікавлений огляд / вступ / посібник, витягнутий із специфікації та з урахуванням їх потреб тощо.
Це може бути корисно організувати порівняльне вивчення довідкової документації, що надається для інших мов, як ваша. Мета цього дослідження - використання досвіду, набутого тими, хто робив це раніше, і навчитися уникати помилок, які вони допустили.
Останнє, але не менш важливе, розглянемо налаштування розробки документації подібним чином до розробки програмного забезпечення. Я маю на увазі такі речі, як контроль за версіями, регулярні випуски, відстеження випусків, забезпечення якості тощо. Можливо, ви хочете зробити деякі компроміси, хоча якщо виявиться, що ваші технічні автори не дуже зручні з такими подібними матеріалами. Ми не хочемо отримувати шалений вміст "в обмін" на ідеальний процес розвитку, чи не так?