Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно?

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

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

Искусство организации рабочего времени (time-management) последнее время обретает всё большую популярность и если раньше это в основном относилось к менеджерам различного уровня, то теперь накопленные знания начинают применяться и в других областях деятельности компании.

Введение

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

Эти правила — не моё собственное изобретение. Скорее, я просто сформулировал их из того опыта, который появился благодаря общению со многими талантливыми техническими и литературными редакторами за более чем десять лет работы. Всё, что я понял в этом деле, сформировалось потому, что другие показали мне путь. У меня не находится достаточно слов, чтобы выразить им в полной мере мою благодарность.

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

Итак — эти 7 правил:

1. Скука убивает
2. Прежде чем начать, выясните точно для себя, какие действия вы ожидаете от читателя, осилившего ваш труд
3. Пишите в соответствии с правильно сформированной структурой
4. Избегайте неоднозначных местоимений
5. Ясность = иллюстрации + слова
6. Когда имеете дело с понятиями, концепциями и т.п., используйте логическую иллюстрацию и пример
7. Не опасайтесь переделок

Однажды появилась необходимость собрать все уроки, обучающие материалы (tutorials) с habrahabr и geektimes в одном месте и немного их систематизировать. В этом сборнике обучаек представлены более 100 статей на тему ардуино с пометкой «tutorial», либо содержащие несложные для новичков проекты на ардуино, а также немного видеоуроков по смежным темам. Статьи разделены на 10 тематик по сферам применения собранных устройств. Также хочется напомнить, что весь обучающий материал, опубликованный на habrahabr и geektimes является интерактивным: в любой момент можно задать вопрос автору в комментариях к статье. Как правило авторы на них отвечают. Этот сборник будет дополняться новыми обучайками (tutorials) по мере их публикации.