Как писать техническую документацию для программ на C#
Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.
Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или — так бывает чаще всего — когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.
Разработчики имеют дело с двумя основными видами документации:
К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.
Пишет о разработке сайтов, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.
4. Документация должна быть сухой
Хотя канцеляризмов нужно избегать, писать надо максимально сухо и по делу. Никаких стихов, метафор, аналогий или шуток — всё это может быть забавным, но не добавляет ясности.
5. В документации не должно быть старого кода
Этот правило больше касается обычных комментариев, чем самой документации. Однако оно очень важное, поэтому приведено здесь.
Никогда не храните в коде старые методы и операторы, даже если они задокументированы. Если что-то не используется в текущий момент — это мусор, от которого нужно избавиться.
Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.
Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.
Где писать документацию в C#
Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.
Лучший способ — писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант — использовать комментарии.
В C# есть два вида комментариев. Однострочные:
Как писать техническую документацию к софту?
Добры день, знатоки!
Проблема
Имеется написанная программа. Необходимо написать для нее техническую документацию. Т.к проект завершен, и на случай если через некоторое время он будет возобновлен, не пришлось изучать код как в первый раз.
Как называется профессия людей, кто занимается только написанием документации?
Можно вспомнить курсовой по программированию.
Как было у нас в учебном заведении, документация делится на 2 части.
1. Общая
2. Специальная
Возможно стандарты разные.
Есть какие-то методологии по написанию документации?
Да. В Вашем случае можно писать по ГОСТ 19. Если проект большой, то по ГОСТ 34. Есть стандарты ISO
Есть какие-то удобные (платные, бурж) SAAS-сервисы для упрощения ведения документации?
Например, в WIki можно ее хранить.
Не нашел особо много информации, по написанию документации, подскажите запросы, по которым смогу «нарыть» больше инфы по этому вопросу, или ткните на конкретные ресурсы/статьи?
В вашем случае это: техническая документация, описание API, описание БД, Javadoc, Doxygen
Как называется профессия людей, кто занимается только написанием документации?
Техписатели, techwriter-ы, разработчики документации.
Сколько стоит в среднем работа людей пишущих документацию?
Оклад техрайтера сильно зависит от квалификации, от языка, на которм он пишет, а также от сложности проекта и типа документации. Можно сказать, что от 30 до 100 тысяч в месяц.
Есть какие-то методологии по написанию документации?
Есть какие-то удобные (платные, бурж) SAAS-сервисы для упрощения ведения документации?
Написания в смысле «руками» или «отдачи» (generation)?
Не нашел особо много информации, по написанию документации, подскажите запросы, по которым смогу «нарыть» больше инфы по этому вопросу, или ткните на конкретные ресурсы/статьи?
Вы лучше сформулируйте, что вам надо. Ответить будет проще. Например, сначала прочитайте вот эти посты:
и конкретизируйте вашу задачу.
Как называется профессия людей, кто занимается только написанием документации?
Согласен с предыдущим участником.
Сколько стоит в среднем работа людей пишущих документацию?
Как создавать и оформлять техническую документацию в IT: рекомендации для начинающих и подсказки для опытных
Поэтому в этой статье поделюсь своим опытом. Он может быть полезным и для продуктовых команд, и для техрайтеров. Не воспринимайте советы как правила: это мои собственные наработки и лайфхаки, которые я подглядывала у коллег.
Эта статья пригодится как начинающим — людям, которые только пришли в профессию и хотят разобраться, с чего начать и каких ошибок избежать, — так и техрайтерам, которые уже успели поработать и набить шишек, которых мой опыт может вдохновить на поиск новых решений при создании документации. По крайней мере я всегда интересуюсь, как пишут коллеги.
«Да что там — просто сесть и написать»
Я обожаю описывать продукты, которые еще не описывали до меня. В этом есть свои преимущества: я сама могу создать структуру документации, составить правила ее форматирования и подходы к стилю. Но это не значит, что можно просто сесть перед окном, которое выходит на океан, и, вдохновляясь вечерним бризом, написать роман!
Сначала рекомендую познакомиться со всеми, кто приобщен к созданию и поддержке продукта: пообщайтесь, соберите информацию, получите доступы к продукту, который необходимо описать.
Совет. Иногда продуктовая команда опасается давать доступ к самому продукту. Говорят, что достаточно и тестового образца. Никогда на это не соглашайтесь. Уже не раз мне приходилось переписывать свою работу, потому что, как оказывалось, то, «на чем тестируют», и то, что ушло в мир как продукт, — разные вещи. Даже интерфейс может заметно отличаться!
А еще продуктовые команды часто «экспериментируют» с наименованием полей и различных кнопок. Иногда бывают «веселые» названия на грани цензуры — ни в коем случае они не должны попасть в приличный мануал продукта! Все скриншоты делайте только с хорошенько прописанного UI реального продукта, чтобы их было не стыдно показать.
Далее посмотрите имеющуюся техническую документацию: юзер-кейсы, технические требования и тому подобное. Мне нравится ходить по доскам Jira продуктовых команд и там собирать информацию. Все собираем, структурируем (можно даже в табличку для удобства). Но даже на этом этапе, когда кажется, что появилось какое-то понимание продукта, писать мануал рано.
Когда вы получили доступы и разобрались с имеющейся информацией (или все еще собираете, ведь начали видеть какую-то логику в полученной информации), время тестировать продукт.
Например, ISO рекомендует создать профили своих читателей:
Техрайтеру нужно перевоплотиться в каждого такого пользователя, пройти его пользовательский путь и фактически решить те задачи, которые перед ним стоят. Иногда это скучно. Иногда приходится еще раз выполнить работу тестировщика, возможно, даже более придирчиво. Но результат того стоит — ваш мануал будет целостным, словно настоящее художественное произведение: в нем будет вступительная часть, основная и концовка.
Вступительная часть — это отдельное решение. Возможно, нужно описать сначала «домашнюю» страницу продукта. Иногда логичнее начать с описания кабинета пользователя. Не волнуйтесь, вы поймете это где-то на этапе «тестирования» продукта. А иногда вам просто скажут, что сейчас нужно описать вот этот функционал, а остальные потом.
Чего я не делаю: уровни, правила, обещания
Не делаю документацию слишком глубокой по уровням. Из своего опыта и по советам коллег знаю, что если вы не Boeing, где каждая статья может иметь подстатьи, вспомогательные или смежные статьи, то ваш максимум — 3-4 уровня документации. Если больше — мануал-гайды-статьи-подстатьи — никто так глубоко не будет читать, потому что будет сложно найти нужную информацию.
Видела примеры, когда для каждой новой фичи продукта техрайтеры делали отдельную статью. Не скажу, что это плохо, но это скользкая дорога. Например, ваш продукт — слишком комплексный аналитический инструмент, который может обрастать дополнительным функционалом. Или этот функционал легко отмирает и заменяется новым. В результате статей становится так много, что их трудно найти в документации. Более того — становится трудно увидеть общую картину продукта.
Совет. Начинайте со статей высшего уровня — описательных, которые будут вступлением к мануалу о продукте или к гайду об отдельном функционале: вот продукт (функционал), он такой, делает вот это, полезен тем-то, а пользователи вот такие.
Когда есть общее описание, можно спускаться на более низкие уровни — к конкретному функционалу (или его элементам). Здесь тоже для каждого гайда или уже отдельных статей должно быть небольшое вступление, разъясняющее, о чем пользователь прочитает дальше.
По возможности я к каждой статье добавляю содержание (это можно делать, например, с Confluence) или пользуюсь различными уровнями заголовков (например, для PDF). Помните: никто не будет читать весь мануал и каждую его статью. Пользователь пробежится по содержанию, затем по заголовкам, возможно, обратит внимание на цветные блоки с подсказками и скриншоты. Но остановится только на том, в чем нужно разобраться.
В конце каждой статьи я еще даю ссылки на смежные материалы — дополнительный или смежный функционал. Никогда не делаю ссылок в середине текста: в PDF не всё кликается, в Confluence ссылки могут ломаться, когда нужно мигрировать на другой райтерский инструмент. Как правило, создаю раздел Read more в конце гайда и добавляю списком несколько ссылок.
Когда уже есть скелет — верхний уровень документации — и немного нарощенного мяса на нижних уровнях, становится понятнее, где и какой функционал должен располагаться в документации.
Для работы с документацией часто использую Confluence. Здесь веду глоссарий, таблицу версионности. Для документации хорошо иметь и статью (отдельный документ) о пользовательских и системных ролях — доступы и разрешения в продукте, который вы описываете
Уже на этом этапе создания документации начинаем понимать, как лучше называть гайды и статьи, даже заголовки разделов. Главное в названиях — чтобы читатель интуитивно понимал и находил нужную ему информацию.
Не начинаю работу над документацией без понимания своего собственного стандарта написания. Например, заголовки. Надо решить, как вы их пишете: как предложения (первая буква большая, другие маленькие) каждая буква большая; используете артикли или нет.
Совет. Заголовки — мое любимое. Иногда наталкиваюсь на такой заголовок-аббревиатуру, что и не догадаешься, о чем речь. Иногда наоборот — две-три строки текста в заголовке — пока дочитал, забыл, зачем зашел.
У меня есть правило, что заголовок должен поместиться в одну строку, а еще лучше — в половину строки. Всегда нужно помнить, что ваш читатель может пользоваться устройствами с различным размером экрана, а текст может иметь различные форматы: PDF, HTML и тому подобное. Отсюда проблема с длиной строки и возможностью его дочитать. Его может «съесть» поле экрана, а вам нужно не раздражать читателя, а дать ему возможность увидеть весь текст сразу.
Я больше пишу на английском языке, поэтому стараюсь делать заголовки с активными глаголами: «удалить__», «создать__». Когда человек ищет ответ на свой вопрос, он должен увидеть в мануале конкретное действие, которое нужно выполнить.
Но не всегда можно поставить активный глагол. Тогда приходится делать заголовок более описательным. Это тоже полезно: читатель увидит описание, и это поможет найти решение проблемы.
Форматирование заголовков и шрифтов лучше выполнять уже после написания основного материала. Для этого прекрасно иметь инструмент для написания текстов, который позволяет накладывать стиль на все тексты и корректировать их централизованно. Советы по его выбору напишу ниже в соответствующем разделе.
Не описываю то, чего не существует. Иногда продуктовые команды обещают, что вот скоро будет какой-то функционал, даже показывают его тестовый образец. А еще могут пообещать исправить, доработать уже завтра, через неделю, в течение месяца, что существенно изменит внешний вид продукта и его функционал. То есть намекают, что это можно уже описать, чтобы потом не переписывать. Ни в коем случае не поддавайтесь! Нельзя описывать ожидаемое. Что на экране — то в документации.
Рабочие моменты
Расскажу о некоторых сложностях, с которыми точно сталкивается каждый техрайтер.
Кнопка есть — функции нет. Это распространенная история. Продуктовые команды не всегда хотят вести свою техническую документацию, поэтому часто помнят только самое свежее о своем продукте. О новой кнопке расскажут все, о соседней, немного более давней, придется искать информацию в других местах. Хорошо, если человек, который ее создавал, еще работает в компании, потому что бывает иначе.
Еще веселее, когда такая кнопка или любой другой элемент просто есть, но не работает. Можно обратиться к команде, чтобы как-то их скрыть, выпилить, но это не всегда возможно, не всегда есть ресурс. В таком случае я игнорирую элемент, не описываю. Хотя остается риск, что пользователь найдет этот нюанс и начнет расспрашивать — тогда будет немного неловко. Как правило, пользователь интересуется в документации тем, что нужно решить именно ему, и не замечает таких «недостатков». Задача техрайтера — предоставить пользователю полезную информацию.
Я так спокойно об этом говорю, потому что продукт — живой организм, он постоянно меняется.
Иногда, например, встречаются сюрпризы с наименованием элементов продукта. Работают себе две команды параллельно, или одна пришла сразу после другой. Они что-то создали, и каждый назвал «что-то» по своему усмотрению. Например, одну и ту же кнопку одни подписали Add, а другие — Create. Вроде и небольшая проблема. Но, во-первых, я за консистентность, а во-вторых, между этими двумя глаголами большая разница. В таком случае я предлагаю командам договориться и остановиться на одном названии, добавляю им объяснения со ссылками на словари, в чем же разница.
Я веду небольшой внутренний канал для команд в Slack, куда могут подписаться все в компании, кому интересно. Там рассказываю о грамматических и стилистических деталях, привожу примеры лучших практик для написания технической документации.
Пример рекомендации о разнице слов
Также стараюсь помочь продуктовым командам WePlay Esports и TECHIIA: создала для них отдельный гайд о стиле, аббревиатурах, грамматике и тому подобном. Это простые и короткие заметки, чтобы они могли проверить себя, если есть необходимость.
Очень плохая документация. Труднее работать с документацией, которую уже написал кто-то до тебя. Иногда из документации выглядывает «кошмар» как по структуре, так и по наполнению. Вероятно, этому есть объяснение, но не стоит тратить время, чтобы в нем разбираться.
Часть документации может оказаться полезной. Поэтому обычно я все оставляю без изменений, а возвращаюсь к критически важным статьям и немного их привожу в порядок только при необходимости. Какие из них являются критическими, можно понять в процессе пользования продуктом. Такую документацию переписываем, адаптируем под имеющийся стиль, что-то отправим в архив. Выделите на работу с уже написанной документацией год. Да, это действительно долго: частичный аудит, отсеивание «кошмаров», архивирование некритических статей (лучше иногда описать все снова).
Иногда компания хочет сохранить предыдущие версии документации, чтобы показать эволюцию продукта. Но даже для этого процесса нужно иметь инструкцию, как и что архивировать, вести версионность и тому подобное. Конечно, это задача техрайтера — нужно иметь целую стопку собственных внутренних правил и стандартов.
Если перед вами стоит выбор между созданием документации с нуля и всем, что я только что описала, советую отдавать предпочтение первому варианту. Есть определенное удовольствие в том, чтобы из ничего создать целый мир документации. А вот разгребать авгиевы конюшни — сомнительная радость.
Совет. Если у вас много команд и много продуктов, можно попробовать применить принцип CI / CD (continuous integration / continuous development). Возможно, даже к работе с документацией, которую создали до вас.
Я подслушала эту историю у своего коллеги Дэвида Бейли: он предлагает научить продуктовые команды создавать их документацию уже на местах. Задача техрайтера здесь — контролировать процесс, дать рекомендации, стандарты, проводить постоянные тренинги, консультировать точечно в вопросах, которые вызывают сомнения.
Документация готовится не единоразово на определенном этапе создания продукта, а проходит весь цикл его жизни. Таким образом она становится содержательнее, несет больше полезной информации
Выбор инструмента для написания документации. Здесь речь пойдет именно о райтерских инструментах.
Прежде чем что-то покупать, нужно долго поработать со своей документацией, понять, как вы пишете, храните, публикуете готовую документацию, какие у читателя требования и потребности.
Прежде чем приобрести свой инструмент, я все попробовала: практически по месяцу пользовалась различными программами, провела несколько демо. Затем всю информацию собрала в таблицу, разобрала достоинства и недостатки и в результате остановилась на MadCap Flare.
Если будет запрос, расскажу, как и среди чего выбирала — преимущества, недостатки, собственные соображения по каждому протестированному инструменту. Напишите об этом в комментариях.
Скрин программы MadCap Flare
И вот счастливая я переношу всю документацию в MadCap Flare. Здесь мы делаем следующее:
Рекомендации для начинающих
В нашей части мира техрайтерство — еще молодая профессия, она только формируется. Иногда на различных IT-ресурсах даже нет такой категории, чтобы отфильтровать по вакансиям или посмотреть статистику по зарплате. Поэтому трудно найти «отраслевые» стандарты, а каждый техрайтер может экспериментировать на свой страх и риск.
Первый совет — искать лучшие практики, читать мануалы компаний с историей и репутацией. У них техрайтерская традиция давно сложилась. Там работают целые отделы, вооруженные своими внутренними стандартами и политиками. Каждое их решение для документации давно обосновано, логично. Ты как машина — пишешь то, что сказали, и так, как написано в инструкции. В этой ситуации нет места для собственного видения, но именно за такими компаниями советую подсматривать в поиске своего стиля.
Google еще и предлагает интересные курсы по техрайтингу для разработчиков, но они будут полезны всем: Technical Writing One ; Technical Writing Two
Второй совет, который уже звучал, — сначала разобраться в продукте, сформировать архитектуру документации, создать свои стандарты и прописать для себя правила ее написания.
Меня иногда просят: покажи, как у тебя. Во-первых, не все можно показывать. Если документ не содержится в открытом доступе, скорее всего, он конфиденциальный. Во-вторых, пользы от этого никакой — другому техрайтеру это не поможет, потому что у каждого свои пользователи и они имеют собственные нужды. Просто «списать» не получится.
Третий совет — не копировать, а искать собственный подход. Работать на рынке с формирующейся техрайтерской традицией — самому участвовать в формировании правил игры. И в этом есть свои маленькие радости.
Маленький тест на определение техрайтера
В завершение хочу сказать, что не все так страшно. Работа с документацией — интересная, если ваши душа и мозг настроены на структурирование любой входящей информации. Но если человек считает себя техрайтером только потому, что умеет писать на английском языке, — должна разочаровать. Наша профессия довольно скучная, нужно уметь усесться и детально разобраться с продуктом; требует много усилий и времени на саморазвитие, а это непрерывный процесс.
Хороший техрайтер — тот, кто обращает внимание на детали и ищет возможность задокументировать должным образом что угодно. Например, как сделать скриншот со Smart TV без специального устройства? Хорошо, если вы работаете в Samsung и в ваших руках есть множество инструментов. А тем, кто подумал о фото экрана телевизора, сделанное на телефон, пока отказано в доступе в мир инструкций, гайдов и мануалов.
Если вы читаете инструкцию к новому гаджету, замечаете недостатки и хотите ее переписать прямо сейчас — вы прошли тест на техрайтера! Велкам в наше комьюнити.
Добавлю здесь свои любимые READ MORE. Список можно продолжить — эти ссылки только для вдохновения:
Как писать документацию к программному обеспечению
Одним из основных направлений деятельности технического писателя является написание технической документации на программное обеспечение.
Разновидностей подобной документации множество: это и спецификации и методики тестирования, и тексты программ, и руководства и всевозможные справки для пользователя. Для удобного использования подобной документации она должна быть кратка по объему, актуальна по содержанию, полна по смыслу.
Существуют два способа написания технической документации.
Способ 1. Написание технической документации для специалистов.
1. Определение необходимой информации. Такая документация будет использоваться специалистами (программистами, разработчиками интерфейса), а значит должная содержать точные сведения по программе. Также могут включаться:
— главные файлы приложения, которые создают разработчики, базы данных, утилиты прочих программ,
— подпрограммы и функции с объяснением назначения каждой из них,
— константы и переменные продукта с указанием способа их применения,
— единая структура программного продукта.
2. Сортировка документации по принципу включения в программный код и создание отдельных документов. Максимальное включение документации в код программы облегчают обновление и сопровождение программного продукта.
3. Инструмент для документирования. Определяется языком, на котором создается данный программный продукт и типом требуемых документов.
Способ 2. Написание технической документации для конечных пользователей.
1. Основание для документации. Документальное сопровождение необходимо для любого программного продукта, чтобы показать пользователям пути его применения и оказать техническое сопровождение. Также в таких документах указываются правовые условия.
2. Определение целевой аудитории. Достаточно редко широкий круг пользователей является специалистами в какой-то конкретной области. Для выделения целевой аудитории:
— определите круг должностей сотрудников, которые будут работать с программным приложением,
— постарайтесь познакомиться с этими людьми и создать свое представление об уровне их подготовки,
— главным в написании технической программы поставьте ответ на вопрос, что может дать данный продукт конкретному пользователю.
3. Выберите формат подачи данных при написании технической документации. Обычно это или справочное руководство, или руководство пользователя.
4. Выберите форму для документов (различные справки, PDF-файлы, печатные руководства и т.д.).
5. Выберите удобный инструмент документирования (программное обеспечение).