Вела документацию как пишется

Фраза «вести документацию»

Фраза состоит из двух слов и 17 букв без пробелов.

Как вести бухгалтерию без бухгалтера. Инструкция для ИП на упрощенке (УСН доходы)

Первичная документация в бухгалтерском учете

Как вести учет в продуктовом магазине!

Складской учёт для начинающих

Огнетушители в детском саду и центре. Как правильно вести документацию

Важно вести документацию на стройке

Синонимы к фразе «вести документацию»

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

Фразы

Написание фразы «вести документацию» наоборот

Как эта фраза пишется в обратной последовательности.

Написание фразы «вести документацию» в транслите

Как эта фраза пишется в транслитерации.

в латинской 🇬🇧 vesti dokumentatsiyu

Как эта фраза пишется в пьюникоде — Punycode, ACE-последовательность IDN

Как эта фраза пишется в английской Qwerty-раскладке клавиатуры.

d t c n b l j r e v t y n f w b /

Написание фразы «вести документацию» шрифтом Брайля

Как эта фраза пишется рельефно-точечным тактильным шрифтом.

Передача фразы «вести документацию» на азбуке Морзе

Как эта фраза передаётся на морзянке.

Произношение фразы «вести документацию» на дактильной азбуке

Как эта фраза произносится на ручной азбуке глухонемых (но не на языке жестов).

Передача фразы «вести документацию» семафорной азбукой

Как эта фраза передаётся флажковой сигнализацией.

Остальные фразы со слова «вести»

Какие ещё фразы начинаются с этого слова.

Остальные фразы из 2 слов

Какие ещё фразы состоят из такого же количества слов.

Комментарии

Что значит фраза “вести документацию”? Как это понять.

У вас есть вопрос или вам нужна помощь?

Спасибо, ваш вопрос принят.

Ответ на него появится на сайте в ближайшее время.

Народный словарь великого и могучего живого великорусского языка.

Онлайн-словарь слов и выражений русского языка. Ассоциации к словам, синонимы слов, сочетаемость фраз. Морфологический разбор: склонение существительных и прилагательных, а также спряжение глаголов. Морфемный разбор по составу словоформ.

По всем вопросам просьба обращаться в письмошную.

Источник статьи: http://xn--80aukmf7a.xn--p1ai/%D0%B2/%D0%B2%D0%B5%D1%81%D1%82%D0%B8/%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D1%8E

Склонение существительного «документация»

Существительное «документ а́ ция» (неод.)

Падеж	Единственное число	Множественное число
Именительный Кто? Что?	документ а́ ция	документ а́ ции
Родительный Кого? Чего?	документ а́ ции	документ а́ ций
Дательный Кому? Чему?	документ а́ ции	документ а́ циям
Винительный (неод.) Кого? Что?	документ а́ цию	документ а́ ции
Творительный Кем? Чем?	документ а́ цией документ а́ циею	документ а́ циями
Предложный О ком? О чём?	документ а́ ции	документ а́ циях

Делаем Карту слов лучше вместе

Привет! Меня зовут Лампобот, я компьютерная программа, которая помогает делать Карту слов. Я отлично умею считать, но пока плохо понимаю, как устроен ваш мир. Помоги мне разобраться!

Спасибо! Я стал чуточку лучше понимать мир эмоций.

Вопрос: сеньора — это что-то нейтральное, положительное или отрицательное?

Ассоциации к слову «документация&raquo

Синонимы к слову «документация&raquo

Предложения со словом «документация&raquo

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

Сочетаемость слова «документация&raquo

Какой бывает «документация»

Значение слова «документация&raquo

ДОКУМЕНТА́ЦИЯ , -и, ж. 1. Обоснование чего-л. при помощи документов. (Малый академический словарь, МАС)

Отправить комментарий

Дополнительно

Значение слова «документация&raquo

ДОКУМЕНТА́ЦИЯ , -и, ж. 1. Обоснование чего-л. при помощи документов.

Предложения со словом «документация&raquo

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

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

Это повлечёт за собой для предпринимателя штраф от 1000 до 2000 руб. с конфискацией товара, на который нет необходимой документации.

Источник статьи: http://kartaslov.ru/%D0%BF%D1%80%D0%BE%D1%81%D0%BA%D0%BB%D0%BE%D0%BD%D1%8F%D1%82%D1%8C-%D1%81%D1%83%D1%89%D0%B5%D1%81%D1%82%D0%B2%D0%B8%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D0%BE%D0%B5/%D0%B4%D0%BE%D0%BA%D1%83%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%86%D0%B8%D1%8F

«Везти» или «вести»: как пишется слово?

«Везти» или «вести» − выбор правильного варианта при написании вызывает трудности. Оба глагола употребляются в русском языке, однако, несмотря на созвучность, различаются по значению. Как правильно пишется и что необходимо усвоить для корректного написания, следует рассмотреть подробнее.

В каких случаях используется слово «везти»

«Везти» − глагол совершенного вида, который образован от «возить» − перемещать что-либо, кого-либо на себе или транспорте неоднократно и в разных направлениях.

Глагол с корнем «-вез-» употребляется в значении:

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

Для проверки оглушенного при произношении «з» в корне следует мысленно представить подлежащее в предложении в 3-ем лице единственного числа.

Примеры предложений

Несколько примеров для рассмотрения:

1. Она поспешила к машине, ей пора везти детей в школу. (Она везет детей)
2. Везти кота в дорожной сумке было неудобно. Он постоянно высовывал из нее голову. (Кто-то везет кота).
3. Деньги в банк ей необходимо было везти самой. (Она везет деньги)
4. Везти на экзаменах начнет только тогда, когда большая часть материала вызубрена. (Везет тогда, когда все вызубрено).
5. Везти на себе всю работу отдела – обычное для него дело. (Он везет на себе).

При такой проверке звонкий «з» слышится отчетливо.

Использование слова «вести»

«Вести» − глагол совершенного вида, который образован от «водить».

Глагол с корнем «-вес-» употребляется в значении:

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

Глухой «с» в корне слова пишется так же, как произносится, проверять его не требуется.

Для того чтобы убедиться в правильном выборе глагола в том или ином контексте, необходимо также подставить подлежащее в 3-ем лице единственного числа.

Примеры предложений

Для более наглядного представления следует рассмотреть несколько примеров:

1. Она наспех застегивала пальто, ей пора вести детей в школу. (Она ведет детей).
2. Вести автомобиль по скользкой дороге было очень опасно. (Кто-то ведет автомобиль).
3. Вести урок в шуме, который устраивали ученики, было невозможно. (Кто-то ведет урок).
4. В первую очередь не следует вести такой образ жизни. (Кто-то ведет образ жизни).
5. Он так до сих пор и не научился вести себя подобающим образом. (Кто-то ведет себя).

Для глагола «вести» синонимом является слово «водить». При замене слов смысл сохраняется.

Ошибочное написание слов «везти» и «вести»

Неправильным считается написание двух разных по значению и написанию глаголов с буквой «с» в корне.

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

1. Ей пора вести сына в детский сад. Однако машина упорно не хотела заводиться.

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

1. Вестисобаку без намордника к ветеринару нельзя. В общественном транспорте

действуют правила перевозки крупных собак.

Согласно написанному, собаку к ветеринару ведут. По контексту везут в общественном транспорте.

Реже допускают ошибки в написании буквы «з» в корне вместо «с». Зная, что есть случаи, в которых она пишется, но, не понимая, в каких именно.

1. Везтиавтомобиль по ночной дороге никому не хотелось. Управлять в таких условиях мог

Из написанного видно, что автомобиль собираются транспортировать. По контексту автомобилем необходимо управлять водителю.

1. Везти престарелого человека без опоры на трость по тротуару со ступенями доставляло неудобства и могло быть травмоопасным.

Из написанного видно, что престарелого человека везут. По контексту ведут по тротуару.

Заключение

Для того чтобы различать глаголы, нужно правильно их соединять для проверки смысла сказанного. В случаях употребления глагола «везти» следует мысленно заменить его на слово «возить». Если смысл сказанного при этом не изменится, в корне буква «з».

Везти (возить) детей, везти (возить) на себе.

Кроме безличного глагола «везти», его написание нужно запомнить.

В случаях употребления глагола «вести» его мысленно необходимо заменить на слово «водить».

Вести (водить) детей, вести (водить) машину.

Источник статьи: http://znanieinfo.ru/orfografiya/vezti-ili-vesti.html

Пишем техническую документацию: руководство для непрофессионала

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

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

Знаете это чувство, как на картинке? Так бывает. Может и не физически, но, скорее всего, люди содрогаются умственно. Меня постоянно мучала мысль, что люди не будут читать мои тексты, если я не оформлю их легко усваиваемым способом. Чёрт возьми, такое может произойти даже с этой статьёй.

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Некоторые из этих советов я узнала из лекции Кевина Берка «Как писать документацию для пользователей, которые её не читают». Кевин поддерживал документацию Twilio с 2011 по 2014 годы.

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

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

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js , но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined . Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

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

Кажется довольно безобидным, верно? Подумайте ещё раз, что происходит, когда вы копируете и вставляете это в командную строку? Вы, скорее всего, получите:

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $ . Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

In a LIVE DEMO, watch @kelseyhightower build a weather application from zero. Starting from the database up to the end point: https://t.co/XAKsOYSHZq pic.twitter.com/1iuHGlVRnR

«Хорошие программисты копируют, великие программисты вставляют»

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

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

• Попросите менее опытных участников проекта честно прокомментировать документацию
• Поощряйте менее опытных участников проекта вносить свой вклад или указывать на пункты документации, которые они не понимают
• Создайте окружение, где поощряются вопросы, в том числе такие, какие могут показаться «очевидными» для опытных участников проекта — это поможет заметить «слепые зоны»
• В процессах код-ревью и CI используйте линтеры, чтобы гарантировать эмпатию и дружественность языка для всех пользователей
• Наконец, попросите прокомментировать документацию реальных пользователей, покажите им текст и спросите, всё ли понятно

Сообщения об ошибках как вид документации

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

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.

Гуманность

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

Пример (ошибка кода состояния 401 у Twilio):

Полезность

Если вы запомните что-то из этих советов, запомните о полезности. Поделитесь с пользователем информацией, как устранить проблему.

Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 4000px по высоте и 4000px по ширине.

Как писать сообщения об ошибках

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

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

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

Сообщения об ошибках в документации

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

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

В случае ошибки 20003 (ошибка кода состояния 401, упомянутая ранее), есть много возможных причин, которые чётко изложены в каталоге.

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

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

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

Мы часто плохо выбираем слова, хотя при написании текста делаем это постоянно. Как и многие названия SDK, каждое слово вызывает у читателя широкий спектр чувств, идей и определений. Вы можете не понимать этого — и часто мы делаем неправильные предположения.

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

Как и с чрезмерным упрощением, мы часто не понимаем, что название плохое. Это то, что Рути называет сбоем эмпатии. Это как сказать, что проблема неудачных слов меня не касается, поэтому её не существует.

Подсказка для США: во избежание случайного расизма используйте слова «запрещённый список» и «разрешённый список» вместо «чёрный» и «белый».
(Источники: Андре Штальц и rails/rails/issues/33677)

Мне это ещё напоминает то, что Рути называет ошибкой мышления новичка. Это как сказать «Мне это совершенно ясно. Не понимаю, как кто-то не может этого понять».

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.

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

Подсказка: я твёрдо верю, что один из величайших «трюков» для решения этих проблем — разнообразие команды, работающей над документацией.

Есть ещё случаи, когда мы признаём ошибку, но не можем или не хотим её исправлять, потому что мы…

• Привязаны к ней
• Не находим времени
• Не видим важности
• У нас нет агентства, чтобы её исправить

Вы можете сказать или услышать: «Но это моё детище!», «Кто убрал мою конфетку?» «Если мы переименуем, всё сломается», «Не верю, что изменение этого названия повлияет на что-то важное».

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

Как правильно подобрать слова?

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

В конце концов, всё неизбежно сводится к субъективной оценке. Однако есть несколько принципов, которые стоит учесть. Рути говорит, что плохие названия — это те, что могут:

• смутить
• огорчить
• ввести в заблуждение
• запутать
• оскорбить

С другой стороны, хорошие названия:

• способствуют внезапному прояснению («вот оно что!»)
• вводят в контекст
• объясняют
• освещают
• оказывают поддержку

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

Подбирать верные слова трудно. Волшебной формулы не существует. Все пользователи отличаются, как и варианты использования продукта; что работает для одних, может не работать для других. Если бы это было легко, у всех была бы намного лучшая документация. Как говорит Рути разработчикам: «Написание программ — это упражнение в придумывании названий. Смиритесь с этим». И если вы пишете документацию для чужой программы, «сообщите разработчику, если его названия не попадают в цель».

Источник статьи: http://habr.com/ru/post/421549/

Проверка орфографии и пунктуации

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

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

Инструмент поддерживает 8 языков.

Орфография

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

Что входит в проверку текста?

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

Грамматика

Для поиска грамматических ошибок инструмент содержит более 130 правил.

• Деепричастие и предлог
• Деепричастие и предлог
• «Не» с прилагательными/причастиями
• «Не» с наречиями
• Числительные «оба/обе»
• Согласование прилагательного с существительным
• Число глагола при однородных членах
• И другие

Грамматические ошибки вида: «Идя по улице, у меня развязался шнурок»

Грамматическая ошибка: Идя по улице , у меня.

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

Пунктуация

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

• Пунктуация перед союзами
• Слова не являющиеся вводными
• Сложные союзы не разделяются «тогда как», «словно как»
• Союзы «а», «но»
• Устойчивое выражение
• Цельные выражения
• Пробелы перед знаками препинания
• И другие

Разберем предложение, где пропущена запятая «Парень понял как мальчик сделал эту модель»

Пунктуационная ошибка, пропущена запятая: Парень понял ,

«Парень понял, как мальчик сделал эту модель»

Какие языки поддерживает инструмент?

Для поиска ошибок вы можете вводить текст не только на Русском языке, инструмент поддерживает проверку орфографии на Английском, Немецком и Французском

Источник статьи: http://rustxt.ru/check-spelling

«Представить» или «предоставить» (информацию, документы, отчет, сведения)?

Выбор однокоренных слов-паронимов «представить» и «предоставить» основывается на точном знании лексического значения каждого из них, сочетаемости с другими словами в определенном контексте.

У слов «предоставить» и «представить» ударным является один и тот же слог, звучат они почти одинаково, тем не менее различаются лексическим значением. Эти однокоренные слова одной и той же части речи являются паронимами.

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

Значение слова «представить»

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

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

Исходя из многоплановости значения глагола «представить» (видовая пара «представлять»), обозначим круг сочетаемости с другими словами.

Сочетаемость слова «представить»

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

Значение слова «предоставить»

Этот однокоренной глагол обладает следующим лексическим значением:

• отдать в чье-либо распоряжение, пользование;
• дать возможность чем-либо распорядиться.

Как видим, его лексическое значение более узкое, чем у однокоренного паронима.

Сочетаемость глагола «предоставить»

• предоставить сведения;
• предоставить информацию;
• предоставить факты;
• предоставить отпуск;
• предоставить кредит;
• предоставить помещение;
• предоставить жильё;
• предоставить политическое убежище;
• предоставить место;
• предоставить выбор;
• предоставить покровительство;
• предоставить свободу

Вывод

В значении «предъявить, вручить для ознакомления, подать на рассмотрение, на подпись начальнику отдела, директору и т.п.» используем словосочетания:

В значении «отдать в распоряжение», то есть поделиться своими знаниями, фактами, правильно скажем:

Источник статьи: http://russkiiyazyk.ru/leksika/predstavit-ili-predostavit.html

7 правил написания технической документации мирового класса

Введение

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

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

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

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

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

1. Скука убивает

Это правило является, по-видимому, самым трудным для формализации и самым важным по необходимости соблюдения. В современном мире интернета действует много сил, борющихся за внимание вашего читателя. Скучное стандартное описание работать не будет. При любых обстоятельствах ваш читатель желает, чтобы было увлекательно и информативно. Поэтому, если ваш текст неясный или неинтересный, то читатель просто щёлкнет пресловутую кнопку «Далее» и перейдёт на другую веб-страницу или на другую ТВ-программу или на свою страницу в Фейсбуке.

Самый простой путь, который я нашёл для пробуждения интереса у читателя, состоит в том, чтобы интересно было мне самому. Я всегда прилагаю значительные усилия, чтобы написать такую статью, которую сам хотел бы прочитать. Я стремлюсь получать удовольствие от того, что пишу. Если мне скучно, то заскучает и читатель. Если я запутался, то запутается и читатель. Если меня не волнует рассматриваемая тема, то читатель, тем более, не взволнуется. Всё очень просто!

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

И снова, всегда стараюсь сделать процесс чтения увлекательным. Я всегда помню, что пишу в конкурентной среде. Имеется множество контента, стремящегося привлечь внимание читателей. Таким образом, мой совет по правилу № 1: если ваши тексты будут интересны вам, то они будет интересными и для читателя.

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

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

Поэтому чрезвычайно полезно для вас чётко определиться, какие действия вы ожидаете от читателя после завершения процесса чтения. Изложите ваше намерение с самого начала. Не оставляйте читателя гадать. Ваше заявление может быть простым и очевидным, как, например: «после прочтения данной статьи вы сможете [впишите свой вариант]». Если вы определились с действиями, ожидаемыми от читателя после прочтения, то процесс написания будет для вас легче с самого начала.

3. Пишите в соответствии с правильно сформированной структурой

Хорошо сформированная структура является тем остовом, вокруг которого растёт ваш документ. Подготовка технического документа без использования некоторой структуры равносильна попытке ориентироваться в метро Нью-Йорка (469 станций!) без схемы. Вы можете оказаться где угодно, но это «где угодно» может оказаться совсем не тем местом, куда вы предполагали попасть.

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

Имеются два правила структурирования, которые я всегда использую:

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

Хотелось бы уточнить. Листинг 1 внизу является примером структуры, которая нарушает первое правило: раздел подуровня требует наличия, как минимум, одной позиции.

Листинг 1: неправильно сформированная структура

1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка

1.1. Шаги, требуемые для приготовления шипучего напитка

1.1.1. Подготовка ингредиентов

1.1.2. Смешивание ингредиентов шипучего напитка

1.1.3. Подача шипучего напитка

Обратите внимание, что в листинге 1 уровень 1 имеет одиночный подуровень: “1.1. Шаги, требуемые для приготовления шипучего напитка“. Такая структура является нарушением первого правила. Чтобы подуровень был правильно сформирован, в разделе должна быть, как минимум, ещё одна позиция. Другими словами, это значит, что на любом данном уровне должно быть, как минимум, два подуровня.

Посмотрите листинг 2 внизу. Обратите внимание, что у уровня 1 теперь имеются три подуровня, из которых раздел «Смешивание ингредиентов шипучего напитка» содержит позиции. Одиночный уровень «Шаги, требуемые для приготовления шипучего напитка» удалён.

Может возникнуть вопрос: «Где раздел Шаги, требуемые для приготовления шипучего напитка». Видно, что этот раздел теперь не является позицией структуры, а перешёл в контент исходного раздела, как показано в листинге 2 внизу.

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

1. Приготовление апельсиново-клюквенно-мандаринового шипучего напитка

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

1.1. Подготовка ингредиентов

1.2. Смешивание ингредиентов шипучего напитка

1.3. Подача шипучего напитка

Обратите внимание, что, хотя листинг 2 демонстрирует структуру с правильно сформированным подуровнем, в контенте раздела уровня 1 имеется только одно предложение. Присутствие одного единственного предложения в контенте раздела структуры нарушает второе правило структурирования — “На каждом уровне структуры должно быть, как минимум, два предложения“.

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

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

1. Приготовление шипучего апельсиново-клюквенно-мандаринового напитка

Апельсиново-клюквенно-мандариновый шипучий напиток может доставить большое удовольствие в жаркий летний день. Напиток состоит из природных компонентов без искусственных ароматизаторов. Апельсиново-клюквенно-мандариновый шипучий напиток не только вкусный, но и чрезвычайно полезный!

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

1.1. Подготовка ингредиентов

1.2. Смешивание ингредиентов шипучего напитка

1.3. Подача шипучего напитка

Почему я так беспокоюсь о правильной структуре и о, по крайней мере, двух предложениях на каждом уровне? Во-первых, соблюдение правила подуровня побуждает меня быть предельно чётким в логической сегментации моего труда. Следование правилу подуровня способствует также тому, что мой текст соединяет мои идеи с общей линией, которая имеет смысл и легко прослеживается.

Во-вторых, правило двух предложений требует от меня написать текст, который является привлекательным, подробным и целесообразным. При записи в «одно предложение» нередко теряются подробности. И, если не рассматривать афоризмы, текст в «одно предложение» — не самое интересное чтение.

4. Избегайте неоднозначных местоимений

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

Рассмотрим абзац в листинге 4.

Листинг 4: абзац с неоднозначными местоимениями

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья показывает, чем они являются и как их использовать.

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

Применительно к абзацу вверху я не удивлюсь, если вы спросите: «Что это за штука „Трафальгабор“? А что такое „Вибитата“? О чём, вообще, этот абзац? О том, как использовать Трафальгаборы? Или о том, как использовать Вибитаты? Или о том, как использовать и те, и другие? Бред какой-то. Вернусь я лучше на свою страницу в Фейсбуке».

Если читатель при чтении вашего описания вынужден тратить время на выяснение, что же вы пытаетесь ему сообщить, то мало того, что информативный поток будет нарушен, но и читатель, скорее всего, будет запутан. Как только вы привели читателя в замешательство, вы его потеряли. Всё другое в мире, направленное на привлечение внимания вашего читателя, становится для него более притягательным, чем ваше творение. Щелчок по кнопке «Далее» — и ваша работа остаётся непрочитанной.

В листинге 4 замешательство порождается неоднозначным использованием местоимения «они» во втором предложении. К чему относится здесь «они» — к Трафальгаборам, Вибитатам или к обоим? Помните, что читатель ничего не знает, что такое Трафальгаборы или Вибитаты. (См. рис. 1 внизу.)

Рис. 1. Использование неоднозначных местоимений запутывает техническое описание

Решение проблемы простое. Посмотрите листинг 5 внизу. Неоднозначное местоимение удалено. Ясность восстановлена.

Листинг 5: устранение неоднозначных местоимений

Трафальгаборы являются базовой компонентой фрейма Вибитатов. Эта статья рассказывает, что такое Трафальгаборы и как их использовать.

Осторожно! Неоднозначное использование местоимений ведёт к техническому описанию, приводящему в замешательство.

5. Ясность = иллюстрации + слова

Посмотрите на фотографию внизу. Скажите, если сможете, о чём это фото?

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

При обращении к иллюстрациям читателям требуется контекст, чтобы внести ясность. Недопустимо, чтобы читатель напрасно тратил время или усилия, пытаясь выяснить, о чём же рассматриваемая графика. Самым лёгким путём устранить неясность с иллюстрациями является обеспечить их надписями.

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

Рис. 2. Инструменты и ингредиенты, требуемые для приготовления апельсиново-клюквенно-мандаринового шипучего напитка

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

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

Вставляя иллюстрацию в ваше описание, следите за тем, чтобы сослаться на неё в тексте указанием её номера и таких слов как «выше», «вверху», «ниже», «внизу». Недопустимо вынуждать читателя при чтении вашей работы тратить время на привязку иллюстрации к тексту или на её поиск в описании. Если вы добавляете в текст, скажем, «Рис. 4», то убедитесь, что где-то в тексте сказано что-то вроде «см. рис. 4 внизу».

Примечание: глаз привлекают изображения

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

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

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

Применим это правило для описания понятия элементарной алгебры.

Понятие «транзитивность отношения равенства» представляет собой следующее:

Теперь приведём логическую иллюстрацию, описывающую это понятие (см. рис. 3).

Рис. 3. Транзитивность отношения равенства является фундаментальным принципом элементарной алгебры

Листинг 6 ниже показывает несколько конкретных примеров для закрепления понимания рассматриваемого положения.

Листинг 6: некоторые конкретные примеры транзитивности отношения равенства

• Если 7 = 3 + 4 и 3 + 4 = 5 + 2, то 7 = 5 + 2;
• Если 12 + 5 = 7 + 10 и 7 + 10 = 6 + 11, то 12 + 5 = 6 + 11;
• Если x + y = z и z = 2a, то x + y = 2a.

Таким образом, правило соблюдено. Мы представили понятие «транзитивность отношения равенства», проиллюстрировали его описательным рисунком и подкрепили примерами.

Теперь рассмотрим понятие, которое ближе к разработке программного обеспечения и несколько труднее для понимания. Таким понятием является наследование моделей объектов проекта (POM = Project Object Model) в Maven (система автоматизированной сборки проектов). Пример 1 ниже представляет рассматриваемое понятие и даёт логическую иллюстрацию, описывающую это понятие. В конце представлена ещё одна иллюстрация, показывающее конкретное использование POM-файлов в ситуации наследования.

Пример 1: выдержка из технического описания наследования моделей объектов проекта (POM) в Maven (система автоматизированной сборки проектов)

Представление наследования POM-файла

POM-файл является XML-файлом, используемым для описания Maven-проекта и для работы с этим проектом. Можно задать, чтобы некоторый Maven-проект наследовал настройки из отдельного родительского POM-файла. Способность наследовать настройки из родительского POM-файла называется POM-наследованием. Вы используете элемент в вашем POM-файле, чтобы задать родительский POM-файл, из которого должно произойти наследование настроек.

Рис. 4 ниже показывает иерархию некоторого условного проекта, являющуюся примером задания мастер-файла РОМ, из которого другие РОМ-файлы могут наследовать общие настройки.

Рис. 4. Можно назначить мастер-файл РОМ, из которого будет происходить наследование общих настроек

Рис. 5 ниже показывает содержание POM.xml-фалов для Maven-проектов stooges-web, stooges-api и stooges-dal. Каждый проект сконфигурирован на использование элемента для наследования настроек из stooges-project.

Рис. 5. Использование элемента для управления Maven-проектом с целью наследования настроек из внешнего РОМ-файла

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

Итак, если требуется предельно ясно представить какое-то понятие, то необходимо включить в текст иллюстрации и примеры.

7. Не опасайтесь переделок

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

Можно сказать об этой работе, перефразируя известную цитату Томаса Эдисона: «Написание технического текста — это на 10% литературное творчество и на 90% переработка!»

Обещанный бонус

Теперь, когда вы знаете 7 правил для создания технической документации мирового класса, я хотел бы поделиться с вами изложением процесса, который я использую при подготовке технических текстов. Здесь немного, но по существу. Я называю этот процесс — “«7 шагов создания технического документа». Итак:

1. Составляю структуру, как минимум, до второго уровня (если удаётся, то и до третьего);
2. Добавляю иллюстрации в структуру для каждого понятия;
3. Делаю подписи под иллюстрациями;
4. Пишу текст в соответствии со структурой, соблюдая правило двух предложений и подстраивая структуру под текст;
5. Редактирую, переделываю;
6. Отправляю результат специалисту по рассматриваемой теме на рецензирование (специалистом по рассматриваемой теме является лицо, которое в состоянии выявить неточности и неясности в описании);
7. Снова редактирую работу на основе отзыва рецензента (рецензентов).

И вот они у вас: 7 правил, 7 шагов. Кому-то надо больше? Теперь, когда вы знаете все мои приёмы, двигайтесь свободно вперёд и делайте мир более правильным, привлекательным, ясным и интересным местом для жизни. Он заслуживает таких усилий.

Источник статьи: http://habr.com/ru/post/303760/

Как писать хорошую документацию

Несколько лет назад я услышал от одного коллеги историю. Он в то время работал начальником отдела технической документации в IT компании. Дело было на собрании, посвященном знакомству с новым техническим директором. Тот, пожав моему коллеге руку и узнав о его роли, пошутил: “Документация? Так ее же не читает никто! Двадцать первый век на дворе”.

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

Возможно, что-то из того, что написано в моей статье, покажется вам “капитанским”. Ничего страшного! Это значит, что вы уже владеете лучшими практиками написания документации. Статья в первую очередь адресована людям, недавно пришедшим в профессию, поэтому, коллеги, если я что-то упустил, или если у вас есть свой взгляд на вещи — пожалуйста, отпишитесь в комментариях.

Что такое “хорошая документация”?

Итак, начнем. Что же вообще такое “хорошая документация”? Подробная? Или написанная с юмором, чтобы было не скучно читать? Для кого-то самая лучшая документация — толстый том, который можно подложить под ножку стола, чтобы не шатался. На мой взгляд, хорошая документация — такая, которая выполняет свою задачу.

А в чем задача документации? Ответов на этот вопрос может быть много. Документация может использоваться для обучения, для справки, или даже служить своего рода рекламой. Я слышал от коллеги историю о том, как менеджер по продукту просил ее написать документацию для нового продукта за три дня, делая упор на том, что “все равно какую, ее никто читать не будет, она нужна только чтобы проект сдать”. И это тоже задача, хоть и очень грустная.

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

Хорошо, допустим. А что позволяет документации выполнять задачу? Какая она, хорошая документация, и как ее создавать? Есть ряд практик, которым мы следуем, когда пишем документацию в Plesk, и сегодня я хотел бы о них рассказать. Итак.

Хорошую документацию легко найти

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

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

Человек начинает пользоваться Plesk.

Человек сталкивается с затруднением.

Человек пытается разобраться с затруднением самостоятельно.

Когда желание преодолеть затруднение пересиливает нежелание тратить время на поиск помощи, человек вводит запрос в Google и открывает первую ссылку в выдаче.

Замечу, что по данным Google Search Console запросы пользователей не включают слово “документация”. Люди ищут “plesk login”, “plesk install”, “plesk ftp” и так далее. Скорее всего, запросы, по которым пользователи находят документацию вашего продукта, выглядят похоже. Чтобы пользователям было проще найти вашу документацию, важно использовать те термины и формулировки, которые они используют. Это особенно важно в случае если поисковая система на вашем сайте документации не очень хорошо производит нечеткий поиск.

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

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

Как же привлечь внимание пользователя за те десять секунд, что у нас есть? Отличная практика — разместить в самом начале каждого раздела краткое (не больше трех-четырех предложений) описание его содержания, в идеале оформив его так, чтобы оно визуально отличалось от остального текста и бросалось в глаза. Сюда же можно добавить ссылки на схожие по смыслу разделы, чтобы облегчить дальнейший поиск пользователям, оказавшимся не там, где они планировали. Вот как может выглядеть такое описание:

В этом разделе вы узнаете, как создать новый FTP аккаунт в Plesk. Если вы хотите узнать, как изменить логин или пароль существующего FTP аккаунта, пройдите по ссылке.

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

Хорошую документацию легко понять

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

В работе я руководствуюсь высказыванием Антуана де Сент-Экзюпери: „Совершенство достигнуто не тогда, когда нечего добавить, а тогда, когда нечего убрать“. Когда готов первый черновик документации для новой фичи, первое, на что я смотрю — можно ли сделать текст проще и короче. Что помогает в этом?

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

Короткие (4-6 предложений) абзацы.

Впрочем, здесь же я хочу упомянуть и еще одно правило, которым руководствуюсь: “Пиши так коротко, как возможно, но не короче”. Не нужно выплескивать ребенка вместе с водой и приносить полноту и ясность в жертву краткости.

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

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

Некоторое время назад я искал технического писателя в свою команду. В тестовом задании, предлагавшемся соискателям, была просьба написать короткую инструкцию, объясняющую, как установить расширение в Chrome. Один из кандидатов снабдил каждый шаг полноразмерным снимком экрана, что раздуло небольшую инструкцию на пару страниц. Чем это плохо? Напомню, что попадая на новую страницу, человек не начинает вдумчиво читать, он пробегается по ней глазами. Большой объем вкупе с обилием иллюстраций отпугивает, несложная процедура кажется чем-то сродни запуску ядерного реактора. Сложилось ощущение, что у соискателя были какие-то установки (“снимки экрана — это хорошо”), но не было понимания, что любым инструментом нужно пользоваться к месту и в меру. Отбор он не прошел.

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

Классический подход к документированию интерфейсов подразумевает последовательное описание индикаторов и элементов управления, размещенных на том или ином экране. Типичный пример — снимок экрана с цифрами-выносками, а под ним — нумерованный список, перечисляющий все, что пользователь и так видит. Введите имя пользователя в поле “Имя пользователя”. Нажмите Ok, когда захотите закончить операцию. Одна коллега метко окрестила документацию, написанную подобным образом, “чукотской справкой”. Что вижу — то пою пишу.

Классический пример “Чукотской справки”

Проблема этого подхода в том, что он не отражает то, как люди пользуются документацией. Если когда-то и были времена, в которые человек, купив программу, внимательно читал от корки до корки лежащий в коробке мануал, они остались в прошлом. Никто не читает документацию, чтобы узнать, что делают все кнопки на экране “Создать домен”. Пользователи обращаются к документации, когда у них возникают затруднения с выполнением какого-то реального сценария, связанного с использованием продукта (создать почтовый ящик, защитить сайт SSL сертификатом, и так далее).

В свете этого, когда пользователь обращается к документации, написанной с использованием классического подхода, ему приходится конструировать процедуру самостоятельно, зачастую из информации, разбросанной по разным разделам. “Хмм, наверное, мне нужно сперва сделать вот это действие, потом вот это, а затем вот это?” И тут сразу возникают следующие проблемы:

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

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

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

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

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

Как мне создать почтовый ящик?

Как мне удалить базу данных?

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

Проиллюстрирую. Я купил себе стиральную машину, потому что мне нужно постирать грязное белье. Это мой сценарий: было грязное белье — стало чистое. Я не умею пользоваться стиральной машиной. Что мне поможет выйти из затруднения и добиться цели? Конечно же, документация.

Что мне предложит документация, написанная с использованием классического подхода? Иллюстрацию панели управления с описанием каждого из элементов, которые на ней находятся. Кнопка А. Регулятор Б. Индикатор В. На самом деле, чтобы постирать белье, мне вовсе не обязательно производить манипуляции с каждым из них. Регулятор выбора режима стирки нужно обязательно повернуть, кнопку включения экспресс-режима можно нажать, а можно и не нажимать, а таймер в этом сценарии вовсе не пригодится. Но я не знаком с тем, как управлять стиральной машиной, поэтому мне приходится сперва ознакомиться с функцией каждого элемента управления (теряя время), а затем решить, какие и в каком порядке нажимать или поворачивать, возможно, методом проб и ошибок (снова теряя время и начиная фрустрировать).

Допустим, я разобрался с тем, как управлять стиральной машиной (потратив время и нервы). Я выставил нужный режим, засыпал стиральный порошок и нажал на кнопку “Пуск”. Но… ничего не происходит. Белье не стирается, цель не достигнута. Почему?

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

Сценарная же документация фокусируется на достижении конкретного результата, как лазер. Делай раз. Делай два. Успех. Если мне посчастливится найти такую для моего сценария, я узнаю, какого шага мне не хватало. А именно: “Откройте дверцу, закрывающую пространство под раковиной, и выкрутите кран от себя до упора”. Отлично, вода забулькала, машина заработала, цель достигнута. Мне даже не пришлось просить помощи у мамы. Спасибо, документация!

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

При написании документации в Plesk мы руководствуемся принципом “Every page is page one” (EPPO) почерпнутым из одноименной книги Марка Бейкера. Чтобы понять его суть, давайте подумаем о том, как люди читают печатные книги, и как ищут информацию в Интернете:

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

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

Таким образом, суть принципа EPPO можно выразить так: каждая страница документации в Интернете должна быть самодостаточной и содержать всю необходимую информацию или ссылки на нее.

Приведу пример. Некоторое время назад для того, чтобы защитить сайт SSL сертификатом, нужно было выполнить в панели Plesk следующие действия:

Сгенерировать запрос на подпись сертификата (certificate signing request) и купить сертификат в центре сертификации (certificate authority).

Загрузить полученный сертификат в хранилище.

Выбрать загруженный сертификат в настройках веб сервера.

Номинально, каждый из приведенных выше пунктов можно рассматривать как отдельный сценарий, но подобный подход может ввести пользователя в заблуждение, так как для достижения цели (сайт защищен SSL сертификатом) нужно выполнить все вышеприведенные действия в правильной последовательности.

В согласии с принципом EPPO, нужно либо объединить все необходимые процедуры в один раздел, либо сделать несколько разделов, связав их ссылками. Например, в начале раздела, описывающего сценарий “загрузить полученный сертификат в хранилище в Plesk” нужно сослаться на раздел о сценарии “сгенерировать в Plesk запрос на подпись сертификата”, а в конце — на раздел о том, как выбрать загруженный сертификат в настройках веб сервера. Благодаря этому, где бы посетитель ни оказался, он сможет сориентироваться, пройти сценарий от начала до конца и добиться желаемого результата.

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

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

Думаю, не нужно объяснять, почему это вдвойне плохо, когда официальная документация содержит недостоверные сведения. Логотип компании на странице документации внушает уверенность, и посетитель тратит время попусту, пытаясь найти кнопку, которую убрали из интерфейса три релиза назад. Когда он понимает, что инструкции неверны, это действует как ушат холодной воды на голову и подрывает доверие и к документации, и к продукту, и к бренду. Единожды солгавший, кто тебе поверит?

Для того, чтобы подобного не происходило, команда технических писателей должна иметь следующее:

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

Достаточно ресурсов, чтобы своевременно отражать эти изменения в документации.

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

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

Еще одно явление, о котором нужно знать, чтобы писать хорошую документацию — это “проклятие знания” (curse of knowledge). Под таким зловещим именем скрывается когнитивное искажение, заключающееся в том, что человеку информированному сложно встать на место человека неосведомленного и увидеть ситуацию его глазами. Если вы когда-нибудь произносили или думали про себя “Ну-у, да это все знают”, вероятно, вы были под воздействием этого искажения.

К счастью, с этим искажением можно справиться. Достаточно помнить о нем и знать, кто целевая аудитория документации, которую вы пишете, и каким багажом знаний обладает ее среднестатистический представитель. Например, если вы документируете клиент Git, можно предположить, что представителю целевой аудитории не нужно рассказывать, что такое система управления версиями или как сделать коммит, но стоит задокументировать, как настроить доступ в репозиторий по SSH ключу. А если у вас в голове возникает мысль “Это, наверное, всем известно”, напомните себе, что вы пишете документацию не для “всех”, а для конкретной аудитории с конкретными знаниями и потребностями.

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

Пользователь А: “Что вы пишете, как для дураков? Разжевываете вещи, которые любому известны!”

Пользователь Б: “Вы знаете, не каждый из нас гений. Пожалуйста, пишите яснее, мне ничего не понятно.”

Как вы думаете, кто из них был прав? На самом деле, правы оба. Судя по всему, раздел, на который они жаловались, как раз и был написан “для всех”, но в итоге не смог сослужить службу никому. Он был слишком сложен для новичка, но не содержал подробностей, интересных эксперту. Как избежать подобных ситуаций? Знать, кто целевая аудитория, и писать с учетом ее потребностей. Ничего страшного, если вы получаете обратную связь только одного типа (“слишком сложно” или “слишком просто”) — это означает, что жалуются люди, не входящие в ЦА (конечно, если подобных обращений не десять штук за неделю).

Хорошая документация оказывает поддержку

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

Приведу пример. В Plesk для защиты от спама используется программа под названием SpamAssassin. Одна из доступных пользователю настроек (spam filter sensitivity) управляет тем, насколько строго фильтр отсеивает входящие письма с подозрением на спам. Работает она просто: пользователь задает значение, выраженное положительным числом не больше 127. Чем меньше число, тем строже фильтр. Вот как могла бы быть описана эта настройка в “плохой” документации:

Введите желаемое число в поле “Spam filter sensitivity” и нажмите Ok.

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

Введите желаемое число (больше 0 и не больше 127) в поле “Spam filter sensitivity” и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот.

А можно ли сделать еще лучше? Как насчет такого:

Введите желаемое число (больше 0 и не больше 127) в поле “Spam filter sensitivity” и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот. Рекомендуемое значение — 7, оно обеспечивает надежную защиту от спама с минимальной вероятностью ложного срабатывания и подойдет большинству пользователей.

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

Как еще можно облегчить жизнь пользователя? Не превращать его в Буриданова осла. Если продукт позволяет добиться того или иного результата несколькими путями, я не описываю их все. Я выбираю оптимальный (самый простой, самый быстрый и так далее) и рассказываю только о нем. Если же между этими путями есть разница (скажем, один быстрее, но подразумевает действия, требующие технических навыков или потенциально рискованные, например, выполнение запросов INSERT или UPDATE в базе данных), я описываю все варианты, эксплицитно указывая на различия между ними, чтобы помочь пользователю выбрать оптимальный для него вариант.

Ну и, конечно же, не забудьте предупредить пользователя в случае если его действия могут привести к неочевидным последствиям, особенно если они необратимы. Нет нужды писать о том, что удалить домен можно при помощи кнопки “Удалить домен”. Это очевидно. Что не очевидно, так это то, что при удалении домена, например, будут автоматически удалены и все резервные копии, или что пользователь лишится доступа в панель, если его учетная запись заблокирована. “Налево пойдешь — коня потеряешь” куда полезнее и информативнее, чем просто “поворот налево”.

Заключение

Теперь вы знаете, как писать хорошую документацию по версии Plesk. Прежде чем откланяться, я хотел бы рассказать еще об одном принципе, который я также позаимствовал у Марка Бейкера. Он звучит просто: “Напиши одну хорошую страницу” (“Write one good page”). Почему он кажется мне очень важным: если у вас уже есть массив документации, написанный по старинке и не соответствующий лучшим практикам, велик соблазн опустить руки. Переписать все с нуля — это целый подвиг! У нас нет столько времени и ресурсов! Но это не обязательно.

Наверняка среди вашей документации есть более посещаемые разделы и менее посещаемые (а если вы не знаете, сколько посетителей читает вашу документацию, то это отличный повод настроить веб аналитику). Переработайте ваш самый посещаемый раздел. Проследите за реакцией пользователей. Сделайте выводы, внесите коррективы, возьмитесь за второй по популярности раздел. И, возможно, пожимая вам руку, новый технический директор скажет “Документация? Это же очень важно! Загляну к вам в три часа, хочу узнать, как вы работаете”.

Источник статьи: http://habr.com/ru/company/plesk/blog/562960/

Документация в порядке

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

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

Небольшое лирическое отступление про то, что меня вдохновило на написание этого текста:

В криминологии есть так называемая теория разбитых окон: «Если в здании разбито одно стекло и никто его не заменяет, то через некоторое время в этом здании не останется ни одного целого окна». То есть, согласно теории, если порядок не поддерживается – люди охотнее его нарушают и не следуют правилам.

Теорию подтверждают эксперименты социологов из Нидерландов. В одном из них ученые приклеивали к рулям припаркованных велосипедов рекламные буклеты и убирали из окрестности все урны. При этом на стене рядом с велосипедами висело заметное объявление о запрете граффити. Для экспериментальной группы исследователи обеспечили сплошь разрисованную граффити стену, а для контрольной – чистую. В результате, у чистой стены выбросили на улицу или перевесили флаеры на чужой велосипед 25% группы из 77 человек, а у раскрашенной – 69%.

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

При разработке ИТ-систем мне кажется очень важным поддерживать порядок в документации. Это и есть та самая “стена”, на фоне которой разворачивается проектная жизнь – на нее смотрят и делают выводы, что это за проект и как там все работает.

Зачем писать

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

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

Если коротко – то “без бумажки ты букашка”. Наша память обманчива и недолговечна. Завтрашний ты обманешь себя сегодняшнего или наоборот. Придет новый человек или уйдет старый – каждый такой финт будет стоить вам дорого. Без общей картины вы будете заниматься микроменеджментом и разработкой того, что уже кем-то сделано, но он забыл вам об этом сказать. Будете делать петли и вставлять друг другу палки в колеса. А через полгода мучительно вспоминать, зачем нужен этот огромный кусок кода, который все тормозит. И это даже не касаясь кейса, когда вы заказали разработку на стороне.

Что писать

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

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

Легче кому-то одному потратить пару часов на документирование, чем всей команде постоянно проверять свою память.

То есть даже когда обстоятельства не в пользу полноценного описания системы и вы работаете в “Agile”-режиме – важно понимать, что какая-то документация существенно облегчит процесс разработки и принесет много пользы .

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

Необходимый минимум

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

Документ-маршрутизатор

Место, откуда можно добраться до всех артефактов проекта. Это может быть страница в Confluence, пространство Notion или просто Google-документ. Важно создать единую точку входа – пусть там будут только ссылки на разные инструменты и источники, но вам не придется запоминать пути поиска нужного файла.

Артефакты проектных процессов

Флоу процесса разработки, статусная модель задач, доски с беклогом, план-график проекта, список нужных контактов и пр. Наличие такой документации налаживает процесс работы и делает его более комфортным. А также сильно разгружает аналитика/менеджера/тимлида и всех, кого волнует выполнение задач и сроки.

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

Артефакты бизнес-потребности и бизнес-процесса

Agile-манифест гласит: “Работающий продукт важнее исчерпывающей документации”. Но нельзя разработать работающий “как надо” продукт без четкого понимания, что же мы все-таки делаем и зачем. Бизнес-требования, схема процесса или просто письмо с постановкой от заказчика – что-то должно быть.

Концептуальная модель системы

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

Используйте IDEF0, “дорожки” BPMN, просто схему или текстовый перечень – главное обозначить принцип работы вашей системы.

Пример верхнеуровнего описания процесса

Классы пользователей и уровни доступа

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

Cценарии использования

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

Логика работы системы

По коду или БД не всегда получается понять смысл функционала. Например, формула расчета стоимости скорее всего задается бизнес-правилами, о которых коду ничего не известно.

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

Описание АПИ

Да пребудет с нами swagger и стандартный формат ответа методов. Если с вами интегрируются внешние компании – не обойтись и без подробного описания параметров.

Тестовые данные

Среды, учетные записи и все, что нужно, чтобы не сводить с ума тестировщика однообразными вопросами.

Ограничения/нефункциональные требования

Вы договорились, что рассчитываете максимум на 100 пользователей? Делаете импорт справочников раз в сутки в час ночи? Внешняя система не умеет принимать какие-то значения? Сделайте приятно себе в будущем – запишите все эти детали.

Другие типы документов

Потребность в некоторых документах возникает вариативно, в зависимости от особенностей проекта:

Архитектура системы

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

Требования к данным

Логическая модель, требования к составу и формату данных, особенности работы с ними и пр. Всё это не всегда покрывается характеристиками БД – в таком случае полезно зафиксировать их в отдельном документе.

Сюда же можно добавить соглашения о формате БД – принципы наименования таблиц и атрибутов, используемые типы данных и пр.

UX/UI макеты и прототипы

Их лучше сразу собирать в одном известном всем месте и держать в актуальном состоянии.

С чехардой в макетах разбираться потом очень сложно. Просто представьте, что у вас хотя бы 3 экрана и у каждого хотя бы по 5 состояний. И аналитик, дизайнер и разработчики смотрят каждый в свой проект в фигме.

Описание интеграций

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

Безопасность

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

Внешняя документация

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

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

Как писать

Несколько инсайтов о работе с документацией:

Не забывайте про актуальность

Стоит писать только ту документацию, которую вы сможете поддерживать в актуальном состоянии.

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

Неоформленные артефакты – тоже документация

Удобно складывать в одно место те артефакты, которые нет возможности обработать и хорошо оформить.

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

Растите культуру документирования в команде

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

Важно договориться, как такая документация будет поддерживаться.

Комментарии в коде не всегда спасают

Структура кода не обязана повторять структуру процесса/функционала и, тем более, бизнес- и пользовательских требований. Поэтому из кода можно понять “как” работает система, но на вопросы “зачем?”, “почему?” и “как должна?” отвечает именно проектная документация.

Планируйте и декомпозируйте работу с документацией

Документирование – это задача, которую легко разбить на небольшие отрезки времени и “размазать” по спринту.

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

Закрывайте техдолг

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

Понять, чего не хватает, просто: представьте, что вы приходите на этот проект сейчас, и никто из предыдущей команды с вами поговорить не может.

Больше схем и диаграмм

Визуальная информация воспринимается легче и быстрее, лучше запоминается. Чем больше данных вы представите графически – тем доступнее и короче будет документация.

Поможет изучение графических нотаций и UML, практика их применения, а также замечательная книга “Говори на языке диаграмм”.

Учитесь писать нехудожественные тексты

Навык написания текстов сильно ускоряет процесс документирования и повышает его качество. Рекомендую использовать https://glvrd.ru. Плюс по возможности почитать “Пиши, сокращай” и “Бизнес-копирайтинг”. Так и работа быстрее пойдет, и тексты станут понятнее и приятнее.

Как итог

Не обязательно подробно документировать всё, или хотя бы выполнять “необходимый минимум” из этой статьи. Всегда полезно сверять часы с реальностью и понимать – что действительно нужно и поможет достичь цели.

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

Даже если у вас нет ТЗ с тезаурусом и перечнем иллюстраций – структурированное и понятное хранение имеющейся документации облегчит жизнь всей команды. А также сподвигнет вас и коллег более собранно и ответственно относиться к проекту.

Источник статьи: http://habr.com/ru/post/549588/

Проверка орфографии и пунктуации

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

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

Инструмент поддерживает 8 языков.

Орфография

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

Что входит в проверку текста?

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

Грамматика

Для поиска грамматических ошибок инструмент содержит более 130 правил.

• Деепричастие и предлог
• Деепричастие и предлог
• «Не» с прилагательными/причастиями
• «Не» с наречиями
• Числительные «оба/обе»
• Согласование прилагательного с существительным
• Число глагола при однородных членах
• И другие

Грамматические ошибки вида: «Идя по улице, у меня развязался шнурок»

Грамматическая ошибка: Идя по улице , у меня.

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

Пунктуация

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

• Пунктуация перед союзами
• Слова не являющиеся вводными
• Сложные союзы не разделяются «тогда как», «словно как»
• Союзы «а», «но»
• Устойчивое выражение
• Цельные выражения
• Пробелы перед знаками препинания
• И другие

Разберем предложение, где пропущена запятая «Парень понял как мальчик сделал эту модель»

Пунктуационная ошибка, пропущена запятая: Парень понял ,

«Парень понял, как мальчик сделал эту модель»

Какие языки поддерживает инструмент?

Для поиска ошибок вы можете вводить текст не только на Русском языке, инструмент поддерживает проверку орфографии на Английском, Немецком и Французском

Источник статьи: http://rustxt.ru/check-spelling