Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Как привлечь интерес к вашему проекту с помощью хорошей документации

23.07.2014

23.07.14Мы не раз уже писали о важности наличия хоть какой-то (а в идеале качественной) документации. Эми Скаварда абсолютно с нами согласна. Представляем вам её размышления по этому поводу.


Нередко я встречаю циклы новостей о сообществах, которые недружелюбны по отношению к женщинам или новичкам, или людям, которые ещё не стали их частью. Под «новостями» я подразумеваю, когда кто-то постит что-то близкое его сердцу о какой-то несправедливости, и когда другие этот пост комментируют или пишут свои собственные сообщения; в общем, мораль этой истории такова – Но мы должны быть лучше, чем они!

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

В последнее время я cую нос в области техники, куда не склонна особо углубляться. Одна из областей – это сборка устройства с помощью документации. Конкретно данное путешествие началось в бытность мою членом сообщества Glass Explorer, и эту историю я рассказывала в моём собственном блоге на amye.org, поэтому я не буду повторять её здесь. Но однажды поздно ночью, когда я копалась в документации о том, что может делать Android, и обо всех (откровенно удивительных) вещах, на которые способно аппаратное обеспечение смартфона (измерять давление атмосферного воздуха, как вам?), меня поразило, что документации сейчас уделяют безумно мало внимания.

Всем приходится читать документацию. Абсолютно всем. Помните случаи, когда вы начинали что-то делать, не удосужившись прочитать инструкцию, а потом удивлялись, почему ничего не работает? Ну-у-у, с кем не бывает. Человек, который «просто скачал инструкцию, чтобы попробовать» и человек, написавший огромную часть кода, оба имеют личную заинтересованность в документации. Конечно, интерес их различен, но он есть. Думаю, тут есть сходство со студентами-второкурсниками, которые только учатся читать ноты, и профессиональным пианистом, которому достаточно лишь на взглянуть на нотный лист. Но обоим нужна партитура, чтобы знать, что играть дальше.

Учитывая такой контекст, документация в вашем сообществе разработчиков открытого ПО многое говорит о том, каким вы ожидаете видеть своё сообщество. Я понимаю, что получу много комментариев о том, какой ваш код хороший и самодокументирующийся. Нет, дорогие дамы и господа, не особо. Ожидать, что код будет самодокументирующимся, всё равно, что помечать отдельные деревья в лесу, не обращая внимания, где этот лес растёт. В Арктике? В тропиках? Каких существ я обнаружу, если подниму вон тот камень? На что я смотрю и где окажусь в следующее мгновение?

Мне нравится документация на Android, потому что это платформа для создания различных реализаций, и поэтому в документации разжёвывается каждый шаг. Она чётко определена и классифицирована, хотя мне ещё встречается незнакомая лексика.

Я недавно натолкнулась на твит @relsqui, и он мне запомнился.

Теория: отсутствие документации развивает синдром позёра. «Мне либо нужно это знать заранее, либо выяснять самому».

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

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

Источник: Get more contributors to your project with better documentation

Тэги: , ,

< Вернуться к списку публикаций

Облако тегов