Комментарии 6
Учебные пособия также требуют больших вложений (по сравнению с другими видами документов). Писать их, вероятно, имеет смысл только в том случае, если многим людям нужно изучить тему. Если это всего лишь несколько человек, встреча с ними лицом к лицу (или с веб-камеры на веб-камеру), вероятно, будет лучшим использованием времени.
Особенно хорошо встреча лицом к лицу получается с теми участниками проекта, которые будут работать на нем лет через 5-10 после тебя… Так что всем было бы легче, если учебник по системе таки писался.
Но вот 'как написать учебник' — с обучением этому умению дело обстоит приблизительно никак.
Хорошее начало.
Но… Есть ещё два критических документа, отсутствие которых часто закапывает продукт или внутренний проект, хотя у него был потенциал.
Это Getting started (документ, описывающий как с нуля получить минимальный рабочий пример для "вот этого самого") и Installation (который кажется тривиальным для инсайдера, и непостижим для постороннего).
Вот без getting started ни один проект не сможет взлететь сам (чужими руками, без индоктринации супервизором). Аналогично, большнство проектов, для которых installation guide не продуман, тоже умрут, даже не будучи попробованными.
А, ещё, важный документ: glossary. Словарь терминов и их объяснение (пусть даже с помощью других терминов).
Сепулька — мономорфизированный инстанс директора с проекцией по оверлейному гарду.
Это Getting started
В терминах этой статьи (правда, я уже ролик успел посмотреть там это более длинно расписано) — tutorial.
Installation
Одно из How-to guides.
А, ещё, важный документ: glossary.
Вероятно, часть reference manual, если оформлено чистом виде — списком, и часть tutorial, когда термины вводят по мере обучения.
Что упущено в статье и ролике — это как хорошо делать переходы из одного в другое. Скажем, когда пишешь how-to, которое по ролику не должно содержать объяснений — только шаги, то все равно систематически хочется как-то "на полях" сослаться и объяснить, почему и для чего мы этот шаг делаем.
И ещё заметил интересную тенденцию: похоже, что слово «инженер» теперь подразумевает, что этот специалист выдаёт на выходе «код» (что бы это ни значило).
Примеры документации с упомянутого divio.com
- Tutorials
- How-to guides
- Technical references
- Explanation (titled “Background” — the name is not important as long as the purpose is clear)
Откровения кофеин-зависимого инженера: как писать документацию