Техническая документация
Все объяснения, задачи и лабораторная в одном месте.
Можно сохранить страницу в PDF через печать браузера. Для печати разборы ответов раскрываются автоматически.
1. Аудитория, задача и information architecture
Объяснение
Документ начинается с аудитории и задачи. Термин объясняется до первого сложного применения. Структура должна позволять быстро найти ответ и понять предпосылки.
Задача для самостоятельного решения
Чем инструкция новичку отличается от reference эксперту?
Показать разбор ответа
Инструкция объясняет подготовку и последовательность с ожидаемым результатом; reference даёт точные параметры и ограничения без обязательного линейного чтения.
2. README и quick start
Объяснение
Quick start приводит к первому работающему результату из явно описанной среды. Команда без ожидаемого вывода оставляет человека без проверки. README также объясняет назначение и границы проекта.
Задача для самостоятельного решения
Что добавить после команды запуска сервера?
Показать разбор ответа
Адрес, ожидаемый ответ, способ остановки и типичную диагностику, если порт занят. Укажите версию среды и необходимые зависимости.
3. Tutorial, how-to и explanation
Объяснение
Tutorial ведёт через учебный пример, how-to решает конкретную задачу, explanation объясняет причины. Смешение всех жанров делает путь новичка непредсказуемым.
Задача для самостоятельного решения
Где объяснить компромисс между двумя алгоритмами?
Показать разбор ответа
В explanation с примерами и ограничениями; в how-to оставить необходимую последовательность и короткую ссылку на объяснение внутри документации.
4. Reference и API documentation
Объяснение
Reference описывает точный контракт: параметры, типы, значения по умолчанию, результат и ошибки. Пример должен быть исполнимым или явно обозначенным псевдокодом.
Задача для самостоятельного решения
Что нужно документировать у API кроме URL?
Показать разбор ответа
Метод, аутентификацию, вход, статусы, схему ответа, ошибки, ограничения, идемпотентность и пример с безопасными данными.
5. ADR, runbook и troubleshooting
Объяснение
ADR сохраняет контекст решения, варианты и последствия. Runbook описывает операционное действие и проверку успеха. Troubleshooting начинается с симптома и диагностических ветвей.
Задача для самостоятельного решения
Почему «перезапустите сервис» — слабый runbook?
Показать разбор ответа
Не указано, когда это уместно, что потеряется и как проверить восстановление. Добавьте предпосылки, диагностику, точную команду и критерии результата.
6. Docs-as-code, review и usability test
Объяснение
Docs-as-code делает изменения рецензируемыми и связанными с версией продукта. Автопроверки ловят битые ссылки и синтаксис, но не понятность. Пользовательская проверка выявляет пропущенные знания.
Задача для самостоятельного решения
Как проверить tutorial перед публикацией?
Показать разбор ответа
Выполнить его в чистой среде человеком, не писавшим текст, записать затруднения и проверить все ожидаемые результаты.
Лабораторная работа
Подготовка
Чистая учебная среда и текстовый README.
Учебный пример
Назначение: локальный трекер задач.
Требования: Python 3; каталог с правом записи.
Запуск: python3 main.py
Ожидается: число сохранённых задач.
Данные: tasks.json в текущем каталоге.
Ошибка JSON: сохранить повреждённый файл и исправить; не очищать молча.
Ограничение: один процесс записи.Как работает пример и что ожидать
Текст сообщает не только команду, но и наблюдаемый результат, место данных и ограничение. Ошибка описана через симптом и действие. Следующий пользователь может проверить запуск без устного объяснения автора.
Итоговая работа
Напишите quick start, how-to, reference и ADR одного сервиса. Проверьте все команды с чистого окружения, добавьте troubleshooting и runbook. Попросите тестового читателя выполнить задачу и исправьте пропущенные предпосылки.
Проверка результата
1. Опишите исходные данные и условия запуска, чтобы другой человек мог повторить работу.
2. Приложите результат обычного сценария и сравните его с ожидаемым.
3. Проверьте неверный вход, граничный случай и отказ зависимости, если она есть.
4. Объясните выбранное решение и известное ограничение.
5. Сохраните исправления после самопроверки вместе с примером, который раньше не работал.
Как оценить работу
По каждому пункту поставьте 0 (не выполнено), 1 (выполнено с пробелами) или 2 (результат воспроизводим и объяснён). Если обязательный сценарий не работает, вернитесь к нему независимо от общей суммы. Это рубрика самопроверки: сайт не исполняет присланный код и не выдаёт автоматическую оценку проекта.