Как писать техническую документацию для программ на C#
Рано или поздно в жизни каждого разработчика наступает момент, когда он не понимает, как работает его код. Выясняем, что с этим делать.
Программисты часто сталкиваются с тем, что не могут прочитать код. Такое случается постоянно: когда только приходят в новый проект, когда проверяют код коллеги или — так бывает чаще всего — когда смотрят результат своей же работы. Чтобы этого избежать, нужно писать и читать документацию.
Разработчики имеют дело с двумя основными видами документации:
К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.
Пишет о разработке сайтов, в свободное время создает игры. Мечтает открыть свою студию и выпускать ламповые RPG.
Правила хорошего тона в составлении документации
Составляя документацию, стоит следовать определенным правилам — они помогают сделать ее более понятной.
1. Документация нужна не всегда
Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.
2. Документация нужна не везде
Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.
Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.
3. Документация должна быть точной
Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:
В этом фрагменте кода объем документации к классу и его свойству не превышает одного предложения. Этого достаточно, чтобы было понятно, что это такое и для чего его нужно использовать.
4. Документация должна быть сухой
Хотя канцеляризмов нужно избегать, писать надо максимально сухо и по делу. Никаких стихов, метафор, аналогий или шуток — всё это может быть забавным, но не добавляет ясности.
5. В документации не должно быть старого кода
Этот правило больше касается обычных комментариев, чем самой документации. Однако оно очень важное, поэтому приведено здесь.
Никогда не храните в коде старые методы и операторы, даже если они задокументированы. Если что-то не используется в текущий момент — это мусор, от которого нужно избавиться.
Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.
Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.
Где писать документацию в C#
Вариантов много. Например, можно сделать это в Word или Google Docs, тогда разработчики смогут скачивать файл из интернета. Некоторые хранят инструкции в печатном виде, но это плохой вариант, потому что документация быстро устаревает.
Лучший способ — писать всё прямо в коде программы. Тогда у каждого разработчика будет доступ к документации в любое время. Самый примитивный вариант — использовать комментарии.
В C# есть два вида комментариев. Однострочные:
Техническая документация
разработка техдокументации по ГОСТ
Как писать техническую документацию?
Создан 29.03.2014 16:37:21
Однако нормативно-технического документа, освещающего приемы и способы изложения технического текста в целом так, чтобы текст стал прозрачным и понимаемым, скорее всего не существует вообще. Но на самом деле эти приемы и способы предельно просты, до слез понятны и подробно расписаны на двух-трех страничках подраздела 6.1.7 той же книги.
Рассмотрим их здесь, чтобы не перелистывать книжку целиком.
Как писать «прозрачный» и понимаемый текст технической документации вообще?
Основная идея изложения текста «вообще» изображена на рисунке. Теперь же, как говорят военные, все сказанное поясним словами: желательно, чтобы текст был структурированным, а не планарным, преобладающим в классической отечественной литературе. Под «планарным» понимаем плоский текст (от лат. planus плоский, ровный).
Вспомните полустраничные абзацы Паустовского, состоящие сплошь из сложноподчиненных и сложносочиненных предложений, или французские пятистраничные тексты Толстого с последующим пятистраничным их переводом в сносках. Тот, кто сумел прочесть «Войну и мир» от корки до корки, достоин памятника при жизни. Установленного рядом с памятником самому Льву Николаичу.
Программное средство представляет собой совокупность программы и сопутствующей ей документации, поэтому понимаемость программы вполне применима как к программной документации, так и к технической документации в целом.
Как писать структурированный текст?
Для «усиления впечатления» текст лучше всего излагать в структурированном иерархическом виде так, чтобы все было «разложено по полочкам», как изображено на рисунке. Текст становится значительно более прозрачным и понимаемым, а еще обретает и «противодураковую защиту».
В жизни случается много чего интересного. Очень часто приходится отбиваться от публики, стремящейся самоутвердиться за чужой счет, от своего рода троллей, только не сетевых, а живых и реальных. Выходки этих малоприятных людей по отношению к хорошо структурированному тексту не проходят по определению ?
Представим себе, что оппонент прикинулся дураком и заявляет, что ему непонятно, для чего предназначены переменные AuthorIT. С таким оппонентом расправиться очень легко, если он, конечно, умеет читать (хотя бы по складам):
Вот так структурированный текст становится прозрачным, защищенным и, если угодно, насильственно понятным. Оппоненту попросту нечего возразить, он загнан в угол и сидит (по меткому высказыванию г-на Лукашенко) как мышь под веником.
Как писать неструктурированный текст?
Если по каким-либо причинам четко структурировать текст не представляется возможным, то разумнее всего изложить его так, чтобы появился «эффект следования», как изображено на рисунке выше. Комментировать, наверное, нечего.
О пользе внедрения в техдокументацию аутентичных текстов ГОСТов и иных нормативных документов
Наверное, приведенный фрагмент книги объяснять словами и не надо. Лучше поведать занимательный случай из жизни.
Поначалу решено было отказаться, но очень уж просили. Буквально вопрос жизни и смерти. Почему бы не разработать, коль так обстоит дело? Опыта проведения различных видов испытаний у «Технической документации» более чем достаточно.
Окружающие повеселились от всей души. Заметим, что в интересах этого же заказчика впоследствии была разработана еще одна ПМ, только уже более сложных механических испытаний, но идеи о проведениии ее экспертизы почему-то ни у кого больше не возникло.
Выводы
Техническая документация в разработке ПО: кто, зачем, когда и как описывает проект
Привет! Меня зовут Даша Григорьева, я технический писатель в компании 65apps. Мы занимаемся разработкой сложных мобильных решений, и моя задача — подготовка технической документации по проектам. Очень часто роль технического писателя бывает недооцененной в компании (не у нас, конечно). Поэтому я хочу рассказать, зачем компании-разработчику нужен такой специалист, что такое технический проект, чем он отличается от ТЗ и почему это все необходимо для разработки мобильного приложения.
Общаясь с большим количеством компаний, я все еще встречаю твердое убеждение в том, что написание технического задания для разработки ПО — пустая трата времени и денег. Мы в 65apps считаем иначе. Поэтому приведу несколько аргументов в пользу технической документации и расскажу, кто и как ее пишет.
Техническая документация позволяет оценить стоимость разработки и согласовать функциональность будущей системы. При возникновении споров о стоимости и сроках разработки той или иной фичи она может стать определенной гарантией для заказчика. С другой стороны, если возникнет потребность в развитии приложения, документация облегчит процесс доработки и даст четкое понимание, возможно ли встроить новую функциональность в существующую систему.
Другой пример — государственные организации или организации, чья деятельность ограничивается или подчиняется законам и надзорным органам. Они обязаны осуществлять разработку ПО по всем правилам и с соблюдением всех стандартов. В таких проектах техническая документация, подготовленная по ГОСТам, — необходимое условие.
И разумеется, грамотно составленная и актуальная документация необходима для того, чтобы каждый участник в процессе разработки мог обращаться к документам, если возникают вопросы по конкретной задаче или по всей системе в целом.
Техническое задание и технический проект — два разных документа. Техническое задание отвечает на вопрос «что нужно сделать?», его составляет аналитик в самом начале проекта. Технический проект разрабатывает технический писатель. Этот документ создается после ТЗ и отвечает на вопрос «как нужно делать?».
Кто пишет техническую документацию
Обычно разработкой ТЗ занимается аналитик. Именно он общается с заказчиком / заинтересованным лицом и выявляет у него требования. В сложных случаях к процессу можно привлечь менеджера проекта, разработчиков, тестировщиков и других специалистов. Чем сложнее проект — тем больше требований к документации. Серьезные заказчики из крупных корпораций и госсектора требуют составлять документацию в соответствии с ГОСТами, а это задача очень трудоемкая, требующая внимательности к деталям и постоянной вовлеченности в процесс. И это не только ТЗ, но и технический проект, полностью описывающий все используемые в разработке решения, подходы и методологии. На него также распространяются ГОСТы. Подготовкой такой документации должен заниматься специалист — технический писатель.
Для крупных проектов иметь в штате технического писателя просто необходимо. Разработка решений для крупных заказчиков может длиться год и более, это довольно долгий срок. За это время возникает достаточное количество изменений, провоцирующих обновление документации. Кроме того, любая долгосрочная разработка ПО предполагает развитие. В этом случае актуальная техническая документация позволит снизить риски, закладываемые в работу исполнителей.
Исключение может быть сделано для представителей госсектора. Таким организациям необязательно иметь в своем штате специалистов соответствующего профиля, так как при возникновении необходимости всегда можно обратиться к профессионалам, которые выполнят качественно свою работу.
Кто такой технический писатель
Строго сформулированного перечня должностных обязанностей технического писателя не существует: каждая компания формирует его сама, а иногда возлагает на такого специалиста и дополнительные задачи. Поэтому иногда бывает сложно даже определить род деятельности технического писателя. В нашей компании такой специалист составляет документацию, необходимую для дальнейшей разработки программного обеспечения.
Для этого он собирает информацию и материалы от участников проекта и документирует эти данные согласно требованиям заказчика, в том числе и в соответствии с ГОСТами. Речь идет о ГОСТ 19 «Единая система программной документации» и ГОСТ 34 «Информационная технология. Комплекс стандартов на автоматизированные системы». Также технический писатель следит за актуальностью технической информации, если это необходимо на длительных и сложных проектах.
Какая техническая документация нужна разработчику
Рассмотрим идеальный с точки зрения ГОСТа процесс разработки системы.
Все начинается с требований заказчика или заинтересованных лиц, которые необходимо выявить и обязательно зафиксировать в документе «Техническое задание».
Техническое задание — это документ, регламентирующий бизнес-цели, общее описание системы, объем работ, границы проекта, а также порядок разработки, оценки и приемки. Данный документ отвечает нам на вопрос «что нужно сделать?» и фактически является постановкой задачи.
Аналитик составляет ТЗ и согласует его со всеми заинтересованными сторонами. После того как собраны и утверждены все требования, можно приступать к созданию прототипов будущей системы и разработке программного обеспечения.
На этом этапе начинается разработка макетов, сценариев, архитектуры и др. Раз уж мы говорим об эталонном процессе разработки, то все это должно быть описано в техническом проекте, который также использует часть информации из ТЗ.
Технический проект — это совокупность документов, описывающих и обосновывающих все подходы, методы, архитектурные и технические решения, применяемые для создания системы. Например, в технический проект включают макеты интерфейсов, описание протоколов для интеграции со смежными системами и оборудованием, пользовательские сценарии, описание алгоритма и их формирование, структура серверов и баз данных, а также другие требования к системе и ее взаимодействию с другими внешними системами.
это далеко не все: существует много стандартов для написания технической документации, и для каждой страны они свои. В отечественных стандартах есть отдельно ГОСТ на создание автоматизированных работ и на программное изделие. Например, технический проект по ГОСТу 19 «Единая система программной документации» может включать в себя следующий перечень работ:
Теперь, когда есть четкое понимание архитектуры, функциональности и дизайна проекта, можно перейти к разработке системы и ее тестированию.
На этапе тестирования, помимо проверки работоспособности системы, проверяется также выполнение всех требований, зафиксированных в документах, что позволяет разрешить спорные ситуации с заказчиком.
Когда составлять техническую документацию
Выше я описала идеальный процесс создания программного обеспечения, но иногда некоторые документы технического проекта составляют уже после этапа разработки.
Есть проекты, в которых важно иметь полную документацию до начала работ. Это касается решений с высокими требованиями к безопасности, соблюдению законодательства и т. д. Например, мобильные приложения для банков. В этом случае важно сначала продумать все детали системы (информационная безопасность клиентов и самого банка, соответствие законам). На это уйдет больше времени, но позволит избежать финансовых и репутационных рисков.
Если разработка идет по методологии Agile, то нет смысла прописывать всю документацию до старта работ. Если заказчику важно работать по спринтам и контролировать ход разработки, документацию можно дописывать параллельно основному процессу.
В нашей компании возможны оба варианта — мы умеем адаптироваться под условия и пожелания заказчика.
На сегодняшний день технический писатель не самая распространенная специальность, но для серьезной компании-разработчика такой сотрудник не менее важен, чем, например, аналитик.
Техническая документация обязательно разрабатывается для госзаказчиков, она необходима и для долгосрочных проектов, на которых с бОльшей вероятностью могут меняться подрядчики. Имеет смысл создавать технический проект для ноу-хау технологий и проектов высокой сложности — документация понадобится отделу QA, чтобы отличить баги и фич.
Секреты написания хорошей документации
Перевод статьи «How to Write Good Documentation».
В этой статье я расскажу о трех шагах, которые помогут вам не забыть, как работает ваш проект.
Вероятно, вам случалось оставить проект сделанным наполовину, а потом уйти на несколько дней в отпуск. Теперь вы узнаете, что нужно делать, чтобы потом без проблем вернуться к работе.
В командах, где я выступаю в роли тимлида, мы стараемся постоянно все документировать. Документация живет своей жизнью параллельно с кодом, она — равнозначный игрок.
Благодаря этому никому не приходится строить догадки, как работает та или иная вещь. Не приходится проводить длительные совещания для обмена знаниями. Хорошая документация экономит нам много времени и избавляет от нудной рутины.
Вопреки распространенному мнению, самая ценная документация пишется не для других людей. Как я написала в одном твите,
«Секрет хорошей документации в том, что ее надо писать параллельно с написанием кода. Ваша первая аудитория — вы сами. Объясните самому себе, что вы делаете. В будущем вы будете благодарны себе за это».
Итак, переходим к конкретике. Вот три шага, которые нужно сделать для написания хорошей документации.
1. Начните со скрупулезного ведения заметок
Воплощая свои идеи в код, обязательно ведите записи. Это поможет вам не забыть важные детали. Хотя впоследствии вы еще распишете все подробно, короткие пометки способны вместить достаточно деталей и вместе с тем не будут сильно отвлекать вас от написания кода.
Пока пишете код, держите открытым файл, где ведете записи. Вносите в него такие вещи как примененные команды, принятые решения, использованные ресурсы. Вы можете записывать:
На этом этапе не обязательно даже писать полными предложениями. Просто следите за тем, чтобы точно передавать контекст, прикладывать соответствующие отрывки кода и полезные URL. Также будет полезным включить опцию автосохранения для этого файла.
2. Объясните свои решения более подробно
Идеальное время для написания пространных объяснений — перерыв после написания кода и перед уходом на обед или переключением на другую задачу.
Чтобы все хорошо и подробно объяснить себе будущему, вам нужны свежие воспоминания о контексте, идеях и решениях.
Вернитесь к своим коротким заметкам и начните расширять их, придерживаясь разговорного стиля. Побудьте своей резиновой уточкой. Объясните, что вы делаете, как будто вы учите кого-то другого. На этом этапе вы можете раскрыть такие темы как:
Не слишком вдавайтесь в детали, сосредоточьтесь на главном. То, что эти объяснения более многословные, чем ваши короткие заметки, еще не значит, что надо писать так, будто вам платят за каждое слово. Просто используйте полные предложения и пишите так, будто объясняете проект коллеге. В конце концов, вы же для себя пишете.
3. Не забудьте упомянуть о предварительных знаниях
Этот шаг лучше делать после полноценного обеденного перерыва или даже на следующий день (но два дня — это уже пожалуй перебор). Перечитайте написанную документацию и заполните все пробелы, которые стали заметны после некоторого дистанцирования от проекта.
Сделайте дополнительные усилия и напишите, какие предварительные знания и навыки нужны для работы над этим проектом (или хотя бы ссылок набросайте). Особенно это касается случаев, когда вы часто использовали разные языки или инструменты. Даже такая мелочь, как вставка ссылки на документацию используемого API, может в дальнейшем сэкономить часы на поиски.
Напишите или прикрепите ссылки на все нужные README, шаги установки, релевантные запросы в поддержку. Для часто осуществляемых действий в командной строке можно использовать самодокументирующийся Makefile. Таким образом вам не придется открывать man для повторяющихся задач при каждом возвращении к проекту.
Спустя некоторое (даже довольно короткое!) время легко забыть какие-то детали, связанные с проектом, но не являющиеся его непосредственной частью. Записывайте все, что сочтете полезным.
Документируйте всё!
В следующий раз, когда поймаете себя на мысли «Я это точно запомню, нет нужды записывать», вспомните какую-нибудь картинку типа фейспалм.jpg.
Проекты создания программ представляют собой намного больше, чем просто код. Чтобы в будущем сразу успешно начать работать с любым своим проектом, документируйте всё! Будь то установленная вами процедура, инфраструктура как код или мимолетная идея на будущее — записывайте! Когда-нибудь вы поблагодарите себя за это.
Вредные советы: как правильно писать техническую документацию?
Советы по грамотному написанию технической документации для пользователей.
Часть 1
В одной из предыдущих статей мы в общих чертах рассказывали, как именно происходит процесс документирования и локализации наших продуктов.
На этот раз под катом – руководство нашего технического писателя Андрея Старовойтова, которое поможет сделать вашу документацию для пользователей проще и понятнее (описанные приемы применяют при документировании своих продуктов Apple, Microsoft и другие компании).
Как известно, хорошая документация – это не роскошь, а средство увеличение объема продаж компании. Если вы собираетесь начать или уже разрабатываете какую-нибудь программу, то, чтобы выйти с ней на мировой рынок, вам понадобится руководство пользователя (оно же User’s Guide) или хотя бы документ, который расскажет покупателям, как начать работать с вашим продуктом (так называемый Getting Started with ).
На каком языке писать документацию – на русском, а затем ее переводить, или сразу на английском – решать вам. В компании Parallels мы выбрали второй подход. Зачастую намного проще сделать описание на английском, так как почти все (а сейчас уже можно сказать, что «все») компьютерные термины в русском языке заимствованы.
Далее по тексту мы остановимся как на русских, так и на английских примерах.
Итак, на что же следует обратить внимание при написании документации?
Типы топиков в документации
При написании топика, для начала надо определить, что это будет за топик 🙂
От этого и будет зависеть, что и как в нем писать.
Существует 4 основных вида топиков:
• Топики, которые описывают, как решить какую-либо конкретную задачу или несколько связанных между собой задач (в английском языке такой вид топиков называется task pages).
Например, «Установите Parallels Desktop» или «Выключите или приостановите Windows». В каждом из таких топиков описывается серия из одного или нескольких шагов, которые должен предпринять пользователь, чтобы добиться определенной цели. Руководство пользователя состоит преимущественно именно из таких топиков.
Обычно пользователи не любят читать, особенно когда текста много. Поэтому надо стараться делать такие топики как можно короче. Идеально, если информация будет представлена в таком виде: «вы можете сделать то-то, для этого нажмите тут и тут» (более подробно task топики будут разобраны в следующей части статьи).
Если разработчик считает, что существует какая-либо дополнительная информация, о которой необходимо знать пользователю, и ее много, то это лучше описать в концептуальных топиках (см. ниже).
• Концептуальные топики (в английском – concept pages). В таких топиках нет инструкций, как решить какую-либо задачу. Они содержат информацию, которая скорее способствует большему пониманию вещей. Например, концептуальные топики используются, чтобы:
— объяснить пользователям, как именно устроен какой-либо процесс;
— рассказать, что можно сделать в настройках приложения;
— описать добавленные фичи в новой версии продукта;
— предоставить дополнительную информацию, которая поможет пользователю лучше понять или решить какую-либо задачу.
Обратите внимание, что дополнительную информацию (в случае, если ее много) надо предоставлять именно в концептуальном топике, чтобы не перегружать task топик.
• Справочные топики (в английском – reference pages) – содержат информацию, к которой пользователь может периодически обращаться, чтобы узнать, что обозначает тот или иной термин, как работает какая-либо функция, и т.д. Хорошим примером таких топиков является словарь в конце гайда (он же Glossary). Справочные топики особенно полезны, чтобы объяснить назначение различных элементов интерфейса.
• Топики, которые описывают как решить какую-либо проблему (в английском – troubleshooting pages).
Например: «Я не могу активировать Parallels Desktop» или «Не могу подключиться к Интернету». В таких топиках описывается, что надо сделать, чтобы решить какую-либо проблему. В них же может содержаться информация, которая поможет понять, в чем причина неисправности.
Основные инструкции для всех типов документации
При создании какого-либо гайда:
1) Сконцентрируйтесь на пользователе
• Вместо того, чтобы структурировать описание продукта на его фичах или элементах интерфейса, попробуйте сконцентрироваться на задачах, которые пользователь вероятнее всего будет пытаться решить.
Например, топик о том, как защитить данные в виртуальной машине, можно назвать 2 способами:
a) «Настройки безопасности» (“Security Settings”), где подробно описать, что можно сделать для защиты данных.
b) Сделать несколько топиков, описывающих конкретные задачи:
— «Защитите данные антивирусом» (“Protect Your Data with Antivirus Software”)
— «Сделайте резервную копию виртуальной машины» (“Back Up Your Virtual Machine”)
Согласно текущим тенденциям в документировании, второй подход предпочтительнее, так как в этом случае пользователю не приходится гадать, надо или не надо что-то сделать, а он получает четкие инструкции, что же именно нужно сделать.
• Фокусируйтесь на задачах пользователя и его уровне технической грамотности.
Например, в документации для обычного пользователя вместо того, чтобы написать «Создайте виртуальную машину» (“Create a Virtual Machine”) стоит написать «Установите Windows или другую операционную систему» (“Install Windows or any Other OS”), так как термин «виртуальная машина» далеко не всем известен. Или другой пример — топик, в котором описывается, как создавать быстрые сочетания клавиш на клавиатуре, лучше назвать «Настройте комбинации клавиш» (“Configure Keyboard Shortcuts”), нежели чем «Настройки клавиатуры» (“Keyboard Settings”).
Хотя чего кривить душой, большинству читателей Хабра было бы понятнее «Настройте шорткаты», но тут уже вопрос, насколько такой термин уместен в официальной терминологии в данное время 🙂
• Если это может быть непонятно, объясняйте, зачем именно пользователю может понадобиться выполнить ту или иную задачу.
• При описании старайтесь использовать те слова, которые пользователь каждый день использует в своей речи. Если технически сложный термин можно заменить словами попроще, всегда старайтесь использовать более простые слова.
Например, «прозрачный» вместо «транспарентный». Если приводить пример из английского языка, то используйте «use» вместо «utilize».
2) Старайтесь дать всю необходимую информацию без лишних слов
«В Спарту пришли послы с острова Самоса — просить помощи. Они произнесли длинную и красивую речь. Спартанцы сказали: «Дослушав до конца, мы забыли начало, а забыв начало, не поняли конца». Самосцы оказались догадливы. На следующий день они пришли в собрание с пустым мешком и сказали только четыре слова: «Мешок есть, муки нет». Спартанцы их пожурили — достаточно было двух слов: «муки нет», — но были довольны такой сообразительностью и обещали помочь».
Если описать функционал слишком длинно – никто не будет его читать. Но совсем «по-спартански» тоже не подойдет, так как если будет написано слишком мало – останутся вопросы и сомнения, пользователи начнут дергать команду поддержки. В общем, тут важно соблюдать баланс.
Чтобы помочь пользователям найти всю необходимую информацию и в то же время описать каждую секцию как можно короче:
4) Привлекайте внимание пользователя правильно
Когда в описании надо привлечь внимание пользователя, используются следующие вводные слова – «Внимание!» (по-английски – Warning!), «Важно:» (по-английски — Important:) и «Примечание:» (по-английски – Note:).
Каждое из этих слов подразумевает свой уровень «важности».
Чтобы не напрягать пользователя напрасно, используйте каждый термин правильно:
Чтобы открыть конфигурацию виртуальной машины, нажмите Действия > Настроить.
Примечание: виртуальная машина должна быть выключена.
Используйте пометку «Примечание:» умеренно – если вставлять ее слишком часто, она забивает текст, и на нее перестают обращать внимание.
По возможности, вставляйте «Внимание!», «Важно:» и «Примечание:» в начале топика, чтобы пользователь узнал об этом перед тем, как начал выполнять какую-либо процедуру. Однако если информация относится только к какому-то конкретному шагу, вставляйте их после этого шага.
(в следующей части статьи мы подробнее разберем топики, которые описывают, как решить конкретную задачу)