Пример документация к программе

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

Внутренняя документация, включенная непосредственно в программу, облегчает чтение кода. Назначение учебного пособия (еще одной формы документации) – научить пользователя применять новую программу; справочное руководство позволяет ознакомиться с описанием команд программного обеспечения.

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

4.1 Пользовательская документация программы

Vitro Process Manager — пример процесса согласования пакета документации

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

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

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

4.2 Документация по сопровождению программы

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

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

Как документировать код | Doxygen урок

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

5. Запуск готовой программы и анализ полученных результатов — после полученного нами файла с *.exe (обычно) разрешением мы можем запустить его и ещё раз проверить (проанализировать) верно, ли работает программа. На этом этапы создания программы закончены.

Структура хранения информации на жёстком диске, кластеры и файлы

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

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

К СЧАСТЬЮ: информация хранится не байтами, а файлами. Файл – наименьшая единица хранения данных. Каждый файл имеет свой адрес.

Чтобы у каждого файла на диске был свой адрес, диск разбивают на дорожки, а дорожки разбивают на секторы (объем сектора – 512 байт) Разбиение диска на дорожки и секторы называется форматированием диска Форматирование – создание физической и логической структуры диска.

Ф ормирование физической структуры диска состоит в создании на диске концентрических дорожек, которые в свою очередь, делятся на секторы.

В процессе форматирования магнитная головка дисковода расставляет в определенных местах диска магнитные метки дорожек и секторов

У гибкого диска две стороны, на которых создается по 80 дорожек. На каждой дорожке по 18 секторов. Объем каждого сектора 512 байтов.

Следовательно, объем гибкого диска = (2∙80∙18∙512) байт = 1474560 байт = 1140 Кбайт = 1,44 Мбайт

Накопитель на жестких магнитных дисках (НЖМД, винчестер) состоит из нескольких магнитных дисков, каждый магнитный диск разбит на гораздо большее количество дорожек на каждой стороне. Поэтому объем НЖМД во много раз больше объема НГМД Минимальный адресуемый элемент информации – кластер, который может включать в себя несколько секторов. Объем сектора составляет 512 байтов.

Размер кластера (от 512 байтов до 64 Кбайт) зависит от типа используемой файловой системы.

Кластеры нумеруются в линейной последовательности (на магнитных дисках от первого кластера нулевой дорожки до последнего кластера последней дорожки).

Виды файловых систем.

FAT12. Файловая система для ОС Windows — выделяет 12 битов для хранения адреса кластера, соответственно, она может адресовать 212 = 4096 кластеров.

Объем кластера по умолчанию равен размеру одного сектора (512 байтов), и поэтому FAT12 не может использоваться для носителей информации объемом более: 512 байт × 4096 = 2 097 152 байт = 2048 Кбайт = 2 Мбайт, следовательно FAT12 используется для дискет.

Файловая система для ОС Windows

FAT16, сегодня FAT32

Выделяет 16 битов для хранения адреса кластера, соответственно, она может адресовать 216 = 65 536 кластеров.

Объем кластера не может быть более 128 секторов (64 Кбайт), и поэтому FAT16 не может использоваться для носителей информации объемом более:

64 Кбайт × 65 536 = 4 194 304 Кбайт = 4096 Мбайт = 4 Гбайт.

FAT32. Файловая система для OC Windows.

Выделяет 32 бита для хранения адреса кластера, соответственно, она может адресовать 232 = 4 294 967 296 кластеров.

Объем кластера по умолчанию составляет 8 секторов (4 Кбайт), и поэтому FAT32 не может использоваться для носителей информации объемом более:

4 Кбайт × 4 294 967 296 = 17 179 869 184 Кбайт = 16 384 Гбайт = 16 Тбайт.

FAT32 используется для жестких дисков самого большого объема.

NTFS. Файловая система для ОС Windows.

Позволяет устанавливать различный объем кластера (от 512 байтов до 64 Кбайт, по умолчанию 4 Кбайт).

Использует систему журналирования для повышения надежности файловой системы. Журналируемая файловая система сохраняет список изменений, которые она будет проводить с файловой системой, перед фактической записью изменений. Эти записи хранятся в отдельной части файловой системы, называемой «журналом» или «логом». Как только изменения файловой системы будут внесены в журнал, журналируемая файловая система применит эти изменения к файлам.

NTFS по сравнению с FAT32 увеличивает надежность и эффективность использования дискового пространства.

Понятие топологии локальной вычислительной сети

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

Различают физическую и логическую топологию. Логическая и физическая топологии сети независимы друг от друга. Физическая топология — это геометрия построения сети, а логическая топология определяет направления потоков данных между узлами сети и способы передачи данных.

В настоящее время в локальных сетях используются следующие физические топологии:

физическая «шина» (bus);

физическая “звезда” (star);

физическое “кольцо” (ring);

физическая «звезда» и логическое «кольцо» (Token Ring).

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

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

Данная топология применяется в локальных сетях с архитектурой Ethernet (классы 10Base-5 и 10Base-2 для толстого и тонкого коаксиального кабеля соответственно).

Преимущества сетей шинной топологии:

• отказ одного из узлов не влияет на работу сети в целом;
• сеть легко настраивать и конфигурировать;
• сеть устойчива к неисправностям отдельных узлов.

Недостатки сетей шинной топологии:

• разрыв кабеля может повлиять на работу всей сети;
• ограниченная длина кабеля и количество рабочих станций;
• трудно определить дефекты соединений

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

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

Данная топология применяется в локальных сетях с архитектурой 10Base-T Ethernet.

Преимущества сетей топологии звезда:

• легко подключить новый ПК;
• имеется возможность централизованного управления;
• сеть устойчива к неисправностям отдельных ПК и к разрывам соединения отдельных ПК.

Недостатки сетей топологии звезда:

• отказ хаба влияет на работу всей сети;
• большой расход кабеля;

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

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

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

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

Топология Token Ring

Эта топология основана на топологии «физическое кольцо с подключением типа звезда». В данной топологии все рабочие станции подключаются к центральному концентратору (Token Ring) как в топологии физическая звезда. Центральный концентратор — это интеллектуальное устройство, которое с помощью перемычек обеспечивает последовательное соединение выхода одной станции со входом другой станции.

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

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

В архитектуре Token Ring маркер передаётся от узла к узлу по логическому кольцу, созданному центральным концентратором. Такая маркерная передача осуществляется в фиксированном направлении (направление движения маркера и пакетов данных представлено на рисунке стрелками синего цвета). Станция, обладающая маркером, может отправить данные другой станции.

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

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

Преимущества сетей топологии Token Ring:

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

Недостатки сетей топологии Token Ring: большой расход кабеля и соответственно дорогостоящая разводка линий связи.

Источник: studfile.net

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

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

Привет! Это Теодора — технический писатель Платформы, жизненно важного департамента Ozon. Документация для нас имеет большое значение, потому что вся компания пользуется нашими разработками:

• инфраструктурой as a service;
• фреймворками и библиотеками на Go, C#, TypeScript;
• трейсингом, мониторингом, логированием, нагрузочным тестированием;
• инструментами для работы с базами данных и аналитикой;
• виртуализацией и контейнеризацией.

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

Зачем вам документация

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

Плюсы хорошей документации:

• увеличивается bus-фактор: знание распространяется между большим числом людей, и его сложнее потерять;
• команда не отвлекается на ответы на одни и те же вопросы и занимается своей работой;
• коллеги быстро находят ответы (в том числе через Ctrl+F ), решают проблемы и разбираются в технологии: как следствие, увеличиваются их продуктивность и доход компании;
• для внешней документации: разгружает сотрудников техподдержки.

Да и, согласитесь, вам просто приятно читать документацию, в которой всё понятно описано и легко искать информацию. Если у вас есть примеры, делитесь в комментариях.

Хорошая ли у вас документация?

Пройдите маленький тест и посчитайте набранные баллы:

Результаты:

• 5 баллов: у вас хорошая документация, автор вами гордится!
• 0–4 балла: есть что доработать — переходите к практическим шагам.

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

Не торопитесь переходить к действиям — сначала налейте чай и просто прочитайте статью.

Шаг 1. Соберите всю информацию

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

• старая документация;
• личные страницы — ваши и коллег (например, в Confluence);
• ответы в чатах;
• репозитории (например, в GitLab);
• Word и другие текстовые редакторы;
• ссылки в закладках браузера.

На будущее: никогда не дублируйте инструкции в разных ресурсах, так их будет сложнее поддерживать:

• легче обновить одну, чем две;
• одну из версий точно забудут обновить — и она будет вводить в заблуждение; как назло всегда будут находить именно её.

Шаг 2. Выбросите мусор

Одна актуальная статья лучше десяти устаревших.

Проверено: если у вас в документации найдут устаревшие сведения, никто не будет читать дальше — спросят у вас лично.

Самый важный шаг перед написанием документации — это избавление от устаревшей информации. Перечитайте всё, что собрали, и удалите неактуальные статьи, разделы и предложения.

Под «избавлением» имеется в виду одно из двух:

• добавление в архив — предпочтительно;
• безвозвратное удаление.

Если после этого вообще ничего не осталось, это нормально.

Если вы детально не знаете начинку описываемой технологии

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

✅ Удачно: позвать на встречу или созвон эксперта из команды (обычно это тимлид или старший разработчик) и вычитать с ним весь материал полностью, не поверхностно.

❌ Неудачно: скинуть материал эксперту и попросить его самого удалить лишнее.

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

После такой «чистки» обычно очень легко дышится — будто камень с шеи снял.

Шаг 3. Найдите частые вопросы и сценарии

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

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

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

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

Шаг 4. Поделите на разделы

Цель — наметить примерный план будущей базы знаний. Он может дополняться, когда появятся новые данные, но пока нужно сделать «скелет» для всего остального.

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

Добавить их все сплошным списком вразнобой — провальный вариант. Ctrl+F тут тоже не всегда поможет, потому что, например, вы пишете в названии страницы «кубер», а ваш читатель ищет «Kubernetes» или «k8s», ничего не находит — и идёт к вам в личку.

Целевая аудитория

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

Подумайте, какие люди будут её читать. Например:

• только ваша команда;
• другие команды, им нужна одна функциональность;
• другие команды, им нужна разная функциональность;
• и ваша команда, и другие команды.

Внешние команды не должны видеть странички «Черновик to do», «[убрать в архив] 2 декабря». Держите их в отдельной папке для черновиков.

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

Шаг 5. Составьте словарь терминов

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

Термины должны легко находиться через Ctrl+F .

Неудачные варианты

Удачные варианты

«Пушка», «долбилка» и «стрелялка»;
Почему: кажется, что это разные термины, возникает путаница. Не найдётся по Ctrl+F .

Почему: все коллеги в Ozon знают этот термин.

«СronJob’ы», «кроны» и «джобы»;
Почему: неясно, составляющие это друг друга или одно и то же. Не найдётся по Ctrl+F .

Почему: все коллеги знают этот термин, он цельный.

«Фэктори» и «фабрика», «эккаунт» и «аккаунт», «экшен» и «действие»
Почему: будьте осторожны с англицизмами. Не используйте их, если есть подходящий термин на русском языке. Не найдётся по Ctrl+F .

«Фабрика», «аккаунт» и «действие»

Почему: популярные, понятные всем термины на русском языке.

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

Шаг 6. Утвердите правила для команды

Заранее обговорите с командой правила и план ведения документации.

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

Обычно инструкции в команде пишут разные люди. Часто процессам ведения документации не уделяют должного внимания.

Если не договориться «на берегу», документация всегда превращается в хаос:

• нет структуры — статьи добавляют куда попало;
• никто не убирает устаревшую информацию;
• команда не всегда знает, что у неё есть в документации;
• много заброшенных статей;
• много пустых статей из 2016 с пометкой «to do»;
• перемешаны внутренние черновики и внешняя документация;
• нет архива;
• ведётся на русском, английском, латинском и древнегреческом.

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

Пример правил по созданию новых страниц:

1. Черновик статьи создавайте в папке для черновиков.
2. Не добавляйте статью в список публичных, пока не допишете.
3. Чтобы перенести статью в список публичных:

• отправьте её в чат команды;
• её должны прочитать минимум два человека, дать обратную связь и утвердить;
• решите с командой, в какой раздел её перенести.

1. Статью можно переносить.

Шаг 7. Напишите тексты

Лучший способ научиться писать хорошие инструкции — это отдавать их на вычитку. Желательно — редактору. Если его нет — любому коллеге. Я не о проверке пунктуации, а о том, понятно ли написана статья, полная ли в ней информация.

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

• Освойте инструменты форматирования там, где вы ведёте документацию. Примеры: макросы Confluence, синтаксис Markdown и HTML.
• Укажите, для кого страница и что в ней описано, — тогда человек сразу поймёт, нужно ли ему это читать.
• Не пишите сплошные тексты — делите их на логические абзацы и разделы. При грамотной вёрстке легче сходу найти ответ.
• Добавляйте оглавление. Его цель — дать читателю возможность быстро понять, в какую часть текста ему нужно переместиться. Если оно получилось на сто пунктов, сократите его или разбейте статью на несколько.
• Оформите разводящую страницу. Это главная страница с основной информацией и разделами по темам. Она нужна, чтобы читатель быстро понял, где искать необходимую инструкцию.
  Пример Ozon Docs
  Пример Yandex Cloud
  Пример Amazon EC2
• Соблюдайте форматирование — не пишите весь текст в заголовке или жирным шрифтом, не создавайте таблицу в таблице, не убирайте весь текст под каты.
• Добавляйте ссылки на другие инструкции и сервисы, если они упоминаются в тексте. Это сильно экономит время читателей. Может, они найдут устаревший дубль из шага 1.
• Избегайте канцеляризмов — они утяжеляют тексты: «для того чтобы в данном процессе осуществить определённую функциональность».
• Выделяйте в тексте важное, но не превращайте его в одни сплошные плашки.
• Укажите контакты команды, чтобы читатели знали, к кому обращаться.

Шаг 8. Добавьте FAQ

FAQ — страница с часто задаваемыми вопросами и ответами на них.

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

Используйте список из шага 3, если он есть.

FAQ — это не полноценная инструкция. Не дублируйте тексты и не делайте ответы очень подробными.

Оптимальный вариант — краткий ответ со ссылкой на полную инструкцию. Например, «Да, это возможно. Подробнее в статье “Как создать N”».

Для продвинутых идеалистов:

Вопросы можно сгруппировать по темам — так их будет проще найти. Такие страницы FAQ обычно очень нравятся разработчикам, но это не принципиально, потому что обычно вопросы ищут с помощью Ctrl+F .

Шаг 9. Продумайте, как вашу документацию будут находить

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

Подумайте, куда ваши коллеги чаще обращаются за помощью:

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

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

Шаг 10. Проанализируйте результат

Лучший источник для анализа — ваша аудитория.

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

Что обычно делаю я:

• Считаю количество запросов в чатах.
• Провожу мини-исследование среди читателей: готовлю открытые вопросы, спрашиваю, долго ли они искали информацию, что именно они искали, нашли ли ответы на свои вопросы.
• Изучаю статистику просмотров в Confluence и Grafana: если за месяц никто не обратился к документации, нужна ли она?

Сама не практикую, но отличная идея:

• Добавить фичу «Оцените статью». Такие макросы точно есть в Confluence.

Если на этом этапе не всё гладко — это нормально, просто будьте готовы что-то дописать, поменять местонахождение статьи.

Итог

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

И помните, что документация — ваш общий продукт.

Буду рада ответить на ваши вопросы. Делитесь мнением и историями в комментариях.

• документация
• онбординг
• техписы
• документация это легко
• база знаний
• документация проекта
• ozon
• ozon tech

• Блог компании Ozon Tech
• Управление разработкой
• Управление проектами
• Управление продуктом
• Подготовка технической документации

Источник: habr.com

Пример документация к программе

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

Как должна выглядеть документация к программе? Что в ней должно содержаться?
Буду рад, если кто-нибудь вкратце опишет или пошлет пример.

Последний раз редактировалось ZeroCount; 01.03.2011 в 02:53 .
Участник клуба
Регистрация: 31.07.2009
Сообщений: 1,403

Документация делится на 3 части. Первые 2 части нужны программистам, последняя — пользователям.

Часть 1 — документация API. Должно отвечать на вопрос «Что это делает?». Это описание классов, методов, полей и т.п. Такая документация должна быть наиболее полной. Для неё, как правило, используют инструменты вроде Doxygen, которые позволяют встраивать документацию в код.
Наример, вот такая фигня (C++, приватные поля класса SoilBlock):

Даёт вот такого вида красоту (это кусок html странички, созданной doxygen): http://img819.imageshack.us/img819/9397/28732417.png
Вот вам пример документации одного из классов огромного проекта, сгенерированного при помощи Doxygen: http://doc.qt.nokia.com/4.7/qpoint.html

Часть 2 — документация к коду. Должно отвечать на вопрос «Как это работает?». Это пояснения к работе кода.
Вот, например:

// передаём клик в стандартный обработчик, чтобы тот передал его в сцену QGraphicsView::mousePressEvent(event); // если сцена приняла событие, оно нам ни к чему if(event->isAccepted()) < return; >if(event->button() == Qt::RightButton) < startHandScroll(event->globalPos()); return; >

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

Часть 3 — документация конечного пользователя. Её имеют взрослые программы (правда, не всегда). Вот пример.

Всё. Но осталось рассказать о важной вещи. Неотъемлемой частью документации к API и к коду является следование хорошим правилам именования. Например:

class Point < public: Point(int x, int y); int x() const; int y() const; void setX(int x); void setY(int y); bool isNull() const; private: int m_x; int m_y; >;

• Классы. Писать как SomeTextHere. Названия должны быть существительными. Например: Point, ImageGallery, BaseballBat.
• Методы (и прочие функции). Писать как someTextHere. Названия должны быть глаголами для void, прилагательными для bool и существительными для прочего. Примеры есть в коде выше: int x(), void setX(), bool isNull(). Также можно использовать специальные названия для конвертаторов, начинающиеся на to, например std::string toString() (возвращает представление класса строкой).
• Переменные. Писать как some_text_here. Аналогично методам: int x, int y, bool is_null, bool has_color, Point left_point. Что важно, поля в классах следует именовать как-то по-особому, например начиная с «m_»: m_x, m_y, m_is_null и т.д. Это позволит с первого взгляда понять, что мы работаем именно с полем, что избавит от возможных ошибок, а также от проблемы Variable shadowing.
• Макросы. Вообще, в хороших местах макросов избегают. И каждый раз когда вы пишите макрос, Обама убивает младенца. Но раз вам не жалко младенцев, пишите SOMETEXTHERE.

Ну нифига ж себе я накатал.

Последний раз редактировалось Obey-Kun; 01.03.2011 в 05:32 .

Источник: www.programmersforum.ru