Хотел написать достаточно пространное вступление, но со временем, пока переводил этот текст, совсем забыл, что именно хотел здесь написать :)

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

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

Как всегда, ссылка на оригинал от Steve Losh - Teach, Don’t Tell.

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

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

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

Этот пост будет о том, что я считаю хорошей документацией, и что следует делать, чтобы её такой сделать. Я несовершенен, поэтому стоит относиться ко всему с долей скептицизма, но я надеюсь, что это будет полезно и даст пищу для размышлений, даже если вы не со всем будете согласны.

Я хотел бы поблагодарить Craig Zheng и Honza Pokorny за корректуру.

Прежде чем читать

До того, как вы прочтете этот текст, я думаю, стоит сначала почитать вот что.

Во-первых, серия “Writing Great Documentation” от Jacob Kaplan-Moss. Он, безусловно, гораздо более компетентен на эту тему, чем я, так что стоит взглянуть на этот материал, если до этого вы его не встречали. Многое из того, что я здесь написал, основано на его идеях.

Другая вещь, которую стоит почитать - “The Science of Scientific Writing” от George Gopen и Judith Swan. Не пугайтесь, что она написана для публикующих статьи ученых. Все описанное прекрасно применимо к программистам, пишущих техническую документацию. Прочтите все целиком. Оно того стоит.

Почему мы пишем документацию?

Давайте начнем. Перво-наперво давайте определимся, почему мы в первую очередь документируем язык программирования или библиотеку. Есть множество вещей, которые мы могли бы тут предложить, но я хотел бы свести их все в одно определение:

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

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

Обучение

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

Вы научите его.

Если взять выпускника школы и сделать из него ученого, как вы это сделаете?

Вы научите его.

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

Вы научите его.

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

Если цель документации - превратить новичка в эксперта, то документация должна учить. Вы должны представить вашу документацию в виде урока (или серии уроков), поскольку это именно то, чем она и является.

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

Остальная части статьи будет почти полностью посвящена тому, как применять образ мышления “документация - это обучение” для написания документации.

Пьеса в семи действиях

Я собираюсь разбавить этот пост небольшими вкраплениями с описаниями плохой документации. Если захотите пропустить эти маленькие тирады - вперед!

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

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

Действие 1: “Читай исходник”

Пьеса начинается с того, что сын с отцом сидят за столом и завтракают. Сын, перед тем, как пойти в школу, чавкает, поедая хлопья, а отец читает что-то на iPad перед работой.

Сын говорит: “Отец, ты говорил, что будешь учить меня водить машину сегодня вечером после школы. Все в силе?”

Отец, не отрывая взгляда от планшета, отвечает: “Конечно, сынок. Авто в гараже, на верстаке набор ключей. Разбери машину на части и каждую внимательно рассмотри, потом собери обратно. После этого отправимся сдавать экзамен.”

Сын спокойно продолжает поедать хлопья.

Если вы используете много библиотек, вы несомненно сталкивались с тем, что в некоторых README написано что-то вроде “читай исходный код”. Каждый раз когда я вижу это, что-то внутри меня умирает.

Исходный код - это не документация. Как можно научиться играть на гитаре, просто внимательно слушая отрывки музыки? Можно ли стать художником, посетив множество музеев? Конечно нет!

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

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

Когда пользователи вашей библиотеки умеют с ней работать, чтение её исходников не будет потраченным впустую временем. Но вы не сможете увидеть конечный результат и оценить перспективы и идеи, которые приведут к этому результату, без дополнительных указаний. Это работа документации.

Орудия труда

Написание хорошей документации не требует множества инструментов.

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

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

Есть два инструмента, которые я порекомендую прежде чем продолжить. Первый даже не инструмент, а скорее умение.

Чтобы написать отличную документацию, необходимо уметь печатать.

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

Steve Yegge в статье “Programming’s Dirty Little Secret” отлично высказывается на эту тему.

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

Я начал практиковаться гораздо больше после того, как приобрел новую гитару, которая была гораздо лучше, чем старая. Если вы, потратив 100 долларов, купите отличную клавиатуру и, в конечном итоге, станете больше писать, оно того стоило!

Скажите спасибо, что прекрасные клавиатуры стоят только от 100 до 300 долларов, а не несколько тысяч, как прекрасные музыкальные инструменты.

Действие 2: “Читай тесты”

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

“Привет, мам”, говорит дочь, “ты все еще собираешься сегодня учить меня управлять машиной?” “Конечно”, отвечает мама, “Поехали.”

После десятиминутной поездки они оказались на заводе Chevrolet.

Дочь озадаченно оглядывается вокруг и спрашивает: “Что мы здесь делаем?”

Мама улыбается и говорит: “Тебе повезло, дорогая, мой друг Джим работает здесь, и он разрешил посмотреть тебе несколько краш тестов нового Malibu! Как только ты посмотришь на разбивающиеся автомобили, мы поедем сдавать экзамен.”

Другой вид “документации” - README, содержащий совет “читать тесты”.

Тесты - не документы.

Снова внесу ясность: когда вы уже знаете, как использовать библиотеку, чтение тестов очень полезно. Но чтобы стать экспертом по этой библиотеке, нужна документация!

Вы не научитесь управлять автомобилем, наблюдая за крэш-тестами. А знание того, как поведет себя машина во время аварии, может спасти вам жизнь, “если вы уже знаете, как ею управлять”.

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

Это верно в некоторых мнимых случаях, но в целом - это выстрел в воздух.

Большинство тестов, чаще всего, относятся к крайним случаям. И эти случаи, это такая вещь, с которой обычный пользователь вряд ли будет часто сталкиваться (на то они и крайние случаи!).

Если повезет, вы сможете найти тест, проверяющий, что библиотека работает корректно при обычном вводе входных данных. Но “обычный ввод входных данных” - это как раз то, с чем пользователь и работает большую часть времени.

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

Как учить

Если вы согласитесь с моей идеей, что цель документации - обучать пользователей, следующий вопрос тривиален: “Как обучать пользователей?”.

Мне повезло иметь возможность полуофициально учить танцам в течение примерно 6-7 лет, а также другим различным вещам неофициально достаточно продолжительное время. И единственный способ действительно узнать, как учить, просто делать это.

Нет ничего лучше, чем сесть друг напротив друга и начать учить человека чему-либо. Если вы хотите писать лучшую документацию, необходимо практиковаться в обучении.

Я не имею ввиду написание плана уроков или чего-то столь же формального. У вас есть хобби (не программирование)? Если есть, посвятите несколько часов в выходные обучению этому своих друзей. У вас будет возможность немного попрактиковаться, а они смогут научиться чему-то новому.

(Если у вас нет хобби помимо программирования, может стоит найти что-нибудь.)

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

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

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

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

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

Кроме уже сказанного я хочу рассказать немного о самом процессе обучения.

Лучшее описание процесса обучения, что я встречал, было в книге How to Solve It. Каждый, кто хочет учить, должно прочитать эту книгу. Отрывок, который попался мне на глаза прямо на первой странице первой главы:

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

Это и есть основа обучения. Вот и все. Это то, как нужно это.

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

Когда вы учите кого-то, нужно поставить себя на его место и пройти этот путь вместе с ним. Держите за руку, обходите препятствия и ловите, когда начнет падать. Не ведите его. Разве только в том случае, когда подвозите на своей машине :)

Процесс должен проходить примерно так: 1. Выясняем, что он уже знает. 2. Выясняем, что вы хотите, чтобы он знал после завершения обучения. 3. Определяем основную идею или концепцию, на основе которой будем двигаться из состояния 1 в состояние 2. 4. Подталкиваем студента в направление этой идеи. 5. Повторяем до тех пор, пока состояние 1 не превратится в состояние 2.

Я очень часто вижу документацию, которая очень внимательно рассматривает состояние 2, а затем просто преподносится читателю в качестве заявления от Всевышнего. Это не обучение. Это рассказ. Люди не учатся через описание, они учатся учась.

Действие 3: “Литературное программирование”

Третье действие начинается с того, что дочь разговаривает со своей матерью накануне своего шестнадцатилетия.

“Слушай, мам,” говорит она, “Я не знаю, приготовила ли ты мне подарок, но если нет, то я хотела бы получить на день рождения уроки вождения.”

Мать улыбается и говорит: “Не волнуйся, мы об этом уже позаботились. Просто дождись завтрашнего дня.”

На следующий день на праздновании своего дня рождения дочь распаковала подарок от своей мамы. Внутри был DVD-диск с шоу “Как это сделано”. Она с недоумением посмотрела на мать.

“На этом диске есть эпизод про автомобильный завод. Как только ты посмотришь его, мы пойдем сдавать экзамен по вождению.”

Худшей тенденцией, замеченной мной в последнее время, стало использование инструментов “литературного программирования”, вроде Docco, Rocco и т.д. и рекомендации пользователям почитать о результатах для документации.

Языки программирования и библиотеки - это инструменты. Знание того, как они сделаны, не означает умения ими пользоваться. Когда вы берете уроки гитары, вы же не посещаете мастера по изготовлению струнных инструментов, чтобы понаблюдать как он придает форму Telecaster’у из ясеня.

Знание, каким образом сделан автомобиль, может помочь, но сначала необходимо знать, как им управлять.

Знание, каким образом сделана гитара, может помочь, но сначала необходимо научиться играть.

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

Но пока этого не произошло, они действительно плохи, поскольку они создают иллюзию, что документация написана и работа, соответственно, сделана (JKM упоминает про это в своей серии). Работа не сделана до тех пор, пока вы не научите пользователей до такой степени, что они станут профессионалами. И только тогда они смогут воспользоваться этими дополнительными штуками.

Анатомия хорошей документации

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

На мой взгляд, хорошую документацию можно разделить примерно на 4 части:

  1. Первый контакт
  2. Черный треугольник
  3. Комок шерсти
  4. Справка

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

Давайте взглянем на каждый из этих компонентов.

Первый контакт

При выпуске публичного релиза языка программирования или библиотеки начальное состояние ваших “пользователей” будет пустым. Вещи, которые они должны узнать, когда столкнутся с вашей библиотекой:

  1. Что это?
  2. Почему я должен про это знать?
  3. Стоит оно того, чтобы изучать?

Ваша документация “первого контакта” должна прояснить эти вещи.

Нет необходимости объяснять с азов. Поставьте себя на место пользователя. Когда вы учите подростка вождению машины, не нужно объяснять, что такое “колесо”. Скорее всего, он уже сталкивался “с такими штуками на колесах, которые что-то перевозят”, вроде газонокосилки или тележки для гольфа.

Кроме того: если вы создаете веб фреймворк, большая часть тех, кто наткнется на ваш проект, скорее всего уже знает, что такое HTML. Это не так и плохо - ошибиться немного в худшую сторону и объяснить чуть больше, чем необходимо, но тут стоит быть более практичным.

Документация “первого контакта” должна объяснять, простыми словами, что написанное вами делает. Она должна показать, почему эта вещь может заинтересовать пользователей. Она сохранит им время? Или наоборот, времени отнимет больше, но предложит больше стабильности? Или это просто клево?

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

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

  • Какую лицензию использует проект (чтобы знать, насколько удобно будет использовать)
  • Где находится баг-трекер (чтобы могли увидеть описанные проблемы)
  • Где исходный код (чтобы могли увидеть поддерживается ли проект в данное время и когда были последние изменения)
  • Где находится документация (чтобы могли просмотреть ее и оценить те усилия, которые придется потратить на освоение проекта)

Действие 4: “Читай Docstrings”

Сцена четвертая. Отец наконец решил сдержать обещание и дать дочери уроки вождения.

“Хорошо, папа”, она сказала, “Я готова. Я никогда раньше не управляла машиной. С чего начнем?”

40-летняя женщина входит в дверь. “Кто это?”, спрашивает дочь.

“Это твой инструктор по вождению, миссис Смит”, отвечает отец, “Она будет сидеть рядом на пассажирском сидении во время твоей двухчасовой поездки к дедушке. Если возникнут вопросы по деталям машины во время поездки, спрашивай, она обо всем расскажет. Вот ключи, удачи!”

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

Комментарии к функциям не предполагают какую-то организацию или порядок (кроме “пространство имен, в пределах которого они должны быть реализованы”). Пользователи должны как-то узнать имя функции, комментарии к которой им нужно посмотреть, и которой они не могут узнать, если вы их не научите.

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

Черный треугольник

Следующая важная часть документации - “черный треугольник”. Это должно быть относительно короткое руководство о том, как получить ваш проект и запустить его.

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

Представьте, вы пришли на ваш первый урок по игре на гитаре и учитель говорит: “Хорошо, мы начнем с изучения 150 различных аккордов. Затем в течение примерно 6 месяцев мы можем поиграть несколько песен.” Никакой преподаватель по гитаре не скажем такого. Он научит вас трем аккордам и даст вам сыграть пару сопливых попсовых песен. Это помогает учащемуся почувствовать, каково быть гитаристом, и позволяет сохранить интерес к обучению.

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

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

Действие 5: “Читай документацию по API”

Следующая сцена происходит год спустя, отец из последней сцены разговаривает с сыном.

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

“Ок, сынок, я знаю, что ты немного боишься управлять автомобилем после того, что случилось с твоей сестрой. Но теперь я устранил проблему.”

Он сует в руки молодому человеку трехсантиметровой толщины книгу. “Задавать вопросы миссис Смит во время пути оказалось неудачным решением, поэтому мы написали по параграфу или двум о каждой детали автомобиля. Прочитай инструкцию от корки до корки и отправляйся на встречу с дедушкой.”

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

Если вы когда-нибудь пробовали объяснить кому-либо суть своего проекта лично, вы, вероятно, заметили, что начали рассказывать про одно, потом переключились на другое, относящееся к первому, а затем вернулись обратно. Обучение - это не прямой путь по алфавиту, а зигзагообразное брожение по чужим мозгам.

Комок шерсти

Это приводит нас к следующему типу документации: “комок шерсти”. К этому моменту, надеюсь, пользователи видели документы “первого контакта” и “черного треугольника”. Вы зацепили их, и они готовы учиться, но пока они все еще новички.

“Комок шерсти” - извилистый, запутанный лабиринт обучения, который из новичков сделает профессионалов. Он перестроит их мозги, периодически слегка подталкивая, пока они не начнут понимать, как ваш проект работает.

Вы скорее всего захотите разделить “комок шерсти” на разделы (если только это не совсем маленький проект). Скорее всего, эти разделы будут соответствовать пространствам имен в вашем API, но если будет необходимость, имеет смысл отойти от такого разделения.

Не бойтесь писать. Будьте краткими, но не страшно, если объяснений будет немного больше. Программисты довольно легко пропускают вещи, которые уже знают, но если вы пропустите важную связь, вы можете оставить пользователей потерянными и заблудившимися.

Имеет смысл сделать оглавление, в котором будет перечислена каждый раздел “комка шерсти”. И у каждого раздела должно быть свое собственное оглавление с разделами внутри. Оглавление - прекрасный способ просмотреть, что вы собираетесь читать, чтобы подготовиться к этому. И, конечно, оно удобно для навигации.

И тут пригодится ваш навык обучения своему хобби и прочитанная статья “How to Solve It”. Поставьте себя на место пользователя и продумайте каждый момент, требующийся для того, чтобы пользователь мог стать профессионалом.

Действие 6: “Читай вики”

В этой предпоследней сцене мать записала своего сына на курсы вождения.

В первый день учитель вручил учащимся учебный план с подробным описанием того, что они будут делать, поговорил об аттестации и пораньше отпустил домой.

На второй день он дал им краткое описание различных деталей автомобиля и описание их работы. А также поговорил о некоторых важных законах, о которых необходимо быть в курсе.

На третий день учитель сообщил, что он болен, и у них будет его заместитель. Этот заместитель рассказывал материал примерно по половину пятого дня учебного плана. А ему нужно было уйти пораньше, так что он оставил вместо себя свою 19-летнюю дочь, чтобы завершить занятие. Она рассказывала половину материала четвертого дня.

На четвертый день пришедшие на занятия ученики обнаружили записку, что занятия отменяются, поскольку преподаватель все еще болен, а замену ему найти не смогли. Тут же висит записка: “СДЕЛАТЬ: мы поговорим о материале позже”.

На пятый день преподаватель частично вылечился, поэтому пришел на занятия и рассказал о теме пятого дня. Его было немного трудно понять, поскольку он был простужен, слова произносил невнятно и часто говорил “cat” вместо “car”.

Все ученики провалили экзамен по вождению.

Вики - это мерзость. Худшая форма “документации”.

Прежде всего: даже если предположить, что инструкции, описанные в вики, работают, написанное разными авторами, чаще всего, никак не согласовано.

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

И еще хуже: вы встречали класс, где присутствует единственный придурок, который постоянно тянет руку и высказывает свои собственные (часто неверные) мнения? Вики представляет собой что-то вроде того, за исключением активного поощрения случайных людей высказывать это мнение.

Сейчас я могу услышать возражение: “Но перенос нашей документации в вики означает, что любой может помочь исправить опечатки!”

Господи.

“Позволит легко исправить опечатки” - худший аргумент для использования вики.

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

И даже если есть множество опечаток, они наименее важная вещь, о которой стоит беспокоиться. Неправильное написание слова не сильно повлияет на эффективность обучения. Но ваши уроки, будучи превращенными в бардак, поскольку написаны тремя разными людьми в течение полугода, станут менее эффективными.

Хранение документации в вики также сильно усложнит или просто сделает невозможным хранение её там, где она и должна быть: в системе контроля версий, рядом с кодом.

Но все это не имеет значение, поскольку в отличие от самой Википедии и вики от видеоигр, это не работает, к чертовой матери.

Сопровождающий проекта запускает вики, садится и похлопывает себя по плечу, говоря: “Я придумал, каким образом другие люди могут сделать эту скучную работу по написанию документации вместо меня. Теперь подождем”.

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

Проект меняется. Новый пользователь читает часть разрозненной документации, которая уже устарела. В конце концов, он выясняет это и жалуется, на что ему отвечают: “Ну, это же вики! Исправьте самостоятельно.”

В обязанности студента не входит исправление кривого плана урока. Да черт возьми, весь смысл иметь учителя состоит в том, что учитель знает, что студенту необходимо учить, а что нет.

Это совершенно нормально, поинтересоваться у студентов, как можно улучшить учебный план. Спросить “какая часть показалась вам трудной” - это прекрасно. И совсем другое дело, просить их написать учебный план самим.

Серьезно: в черту вики. Они плохи и ужасны. Не используйте их. Вместо этого, найдите время и силы для написания какой-то реальной документации.

Справочник

Последний вид документации называется “справочник”. Этот раздел предназначен для тех пользователей, которые прошли весь “комок шерсти” и оказались по ту сторону. Теперь они ваши эксперты, и справочник должен поддерживать их, поскольку они используют ваш проект в своей повседневной работе.

Этот раздел должен содержать те вещи, которые, скорее всего, потребуются опытным пользователям:

  • “Документация по API” для каждой части вашего проекта, с которой может столкнуться пользователь
  • Полный лог изменений, с подробным описанием обратно-несовместимых изменений между версиями
  • Подробности внутренней реализации проекта
  • Правила участия в проекте (если проект принимает сторонние изменения)

Инструменты вроде JavaDoc могут создавать что-то, похожее на первый пункт, но я поделюсь тем же мнением, что и Jacob Kaplan-Moss:

Автоматически сгенерированная документация практически ничего не стоит. В лучшем случае, это просто улучшенный вариант просмотра исходников, но, по большей части, проще прочитать исходники, чем проходить по всему тому бреду, который создают инструменты для автоматического создания документации. Единственная вещь, для чего годятся эти инструменты - заполнение отпечатанных страниц, когда по контракту требуется предоставить определенное количество печатной документации. Я чувствую себя особенно разъяренным, когда нажимаю на ссылку “Документация” и вижу автоматически сгенерированную документацию.

Не существует замены для написанной, составленной и отредактированной вручную документации.

Да, наверно можно найти инструмент для чтения исходников проекта и высера нескольких файлов HTML с именами функций внутри. Может они даже будут включать в себя комментарии к функциям.

Я настоятельно советую писать документы по API вручную. Это потребует немного больше времени для набора текста, но и результат будет гораздо лучше по множеству причин.

Документация по API и комментарии к функциям, хотя и похожи, преследуют разные цели. Комментарии к функциям предоставляют необходимое в пылу программирования в похожем на REPL формате. Документы по API могут позволить себе роскошь давать более подробную информацию, а также ссылки на другие вещи, о которых пользователь может захотеть узнать, пока он по ним пробегается. Документам по API также стоит быть пригодными для гугления.

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

Некоторые скажут: “Но скопировать и вставить - это вредно! Это лишние усилия! Как вы будете синхронизировать изменения в документам по API и комментариях к функциям?”

Мое мнение таково: если публичный API часто меняется, вы просто усложняете жизнь своих пользователей, поскольку им придется постоянно обновлять свой код для работы с вашим. Так что, как минимум, вы можете сделать вашу жизнь менее сложной, обеспечивая их лучшей документацией в качестве “обезболивающего”.

Автоматически сгенерированная документация не имеет к этому отношения. Она тянет всю информацию со всего кода без учета общей структуры и видения. Вы можете, конечно, или заморочиться документами по API в разделе “справочник”, или вы можете вспомнить о чувстве собственного достоинства и написать насколько это возможно лучшую документацию!

Действие 7: “Новая надежда”

Финальное действие нашего спектакля происходит на стоянке торгового центра днем в воскресенье. На парковке единственная машина. Внутри семья: мать и отец, которые учат сына управлять автомобилем.

Они начинают посередине парковки, вдалеке от препятствий. Сын садится на водительское сидение, а родители кратко объясняют, что делает каждый элемент управления. Они позволяют проехаться немного вокруг парковки, чтобы он мог получить немного представления о том, как работает автомобиль.

Когда приходит время припарковаться, он переключает рычаг на “паркинг” и отстегивает ремень безопасности. Его мать напоминает про “парковочный тормоз”. И он понимает, что он должен использовать его при парковке. Набор нейронов связывается в его мозгу, и он запомнит про использование парковочного тормоза всю оставшуюся жизнь.

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

У него постоянно возникают вопросы. Иногда у родителей есть ответы, иногда в их знаниях есть пробелы, которые они со временем закрывают.

Постепенно сын узнает все больше и больше. Он получает водительские права и начинает управлять самостоятельно.

Когда спустило колесо, он читает руководство по эксплуатации автомобиля и решает проблему.

Он смотрит серию “Как это сделано” об автомобиле, поскольку ему интересно, как тормоза, которые спасли ему жизнь на прошлой неделе, реально работают.

Однажды перестают работать стеклоочистители. Он открывает капот и определяет проблему, сам починив поломку.

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

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

Он сидит в машине со своей дочерью, и он учит её управлять автомобилем.