Как написать тз для сайта


Техническое задание на сайт / Хабр

UPD: Продолжение статьи с примером техзадания

Не так давно на хабре были две статьи (Согласно техническому заданию и А зачем мне ТЗ? Я и так знаю!) посвященные техническим заданиям. У меня обе статьи вызвали, мягко говоря, недоумение, в особенности статья «Согласно техническому заданию». На мой взгляд, это вообще вредная статья, которая приводит к неверному понимаю сути ТЗ. В связи с этим хочу выразить свой взгляд на этот вопрос. Не буду говорить обо всех тех. заданиях, слишком широка тема, но думаю смогу рассказать о ТЗ на сайт.

То описание технического задания, о котором речь пойдет ниже, не является пересказом ГОСТа, но скорее является его творческой переработкой, хорошо сдобренной горьким опытом. Описанный ниже подход к ТЗ не охватывает все аспекты сайтостроения, но задает общее направление.

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

1. Обоснование необходимости ТЗ

А зачем вообще нужно ТЗ на сайт? Заказчик говорит: «Нужен следующий сайт: каталог товаров, корзина, форма заказа, доставка, мы на карте, о нас, обратная связь». Что не ясно? Ничего необычного, всё обыденно и рутинно.

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


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

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

Если «вычесть» одну картинку из другой, сделать, так сказать, diff, то мы получим разницу в ожиданиях заказчика и планах разработчика. И разница эта может быть весьма существенной:

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

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

Однако, есть очень важный момент: тех. задание не должно и не может свести diff к нулю! Поясню почему.

И diff и ТЗ имеют свою стоимость, причем стоимость нужно понимать более широко, чем просто деньги. Это деньги, время, потраченные нервы, испорченные отношения и т.д.
Стоимость diff — это стоимость изначально неоговоренных доработок, стоимость ТЗ — это, собственно, стоимость ТЗ. Чем более подробное и детализированное техническое задание, тем выше его стоимость, но тем меньше величина и стоимость diff-а, и наоборот.

Если рассматривать две крайности, когда тех. задания просто нет, нет совсем, т.е. вообще, и мы сделали фотохостинг, а заказчик желал интернет-магазин, то diff будет равен всему проекту, и его стоимость будет равна стоимости проекта (придется выкинуть наш фотохостинг и сделать магазин). При этом стоимость ТЗ равна нулю. Другая крайность, это когда техническое задание и есть сам реализованный проект, т.е. оно детализировано полностью, т.е. до строк кода, переменных и стилей css. В этом случае diff равен нулю, а стоимость ТЗ равна стоимости проекта (т.к. ТЗ уже является реализацией). А между этими крайностями находится реальность, которая отражена на этом графике:

Синяя линяя — стоимость ТЗ, она растет с ростом детализации, красная линия — стоимость diff-а, его стоимость, напротив, падает с ростом детализации.

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

Отсюда важный вывод: ТЗ должно хорошо описывать проект, но не более того.

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

2. Что в нем должно быть и чего нет. Формулировки

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

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

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

Вообще, ТЗ надо писать так, как будто вы с заказчиком не сошлись во мнениях и ваш спор будут разбирать в суде, основываясь на тексте тех. задания. А у вас в ТЗ написано «сделать дизайн, который понравится заказчику». Судья спрашивает: «Заказчик, Вам нравится дизайн?». Заказчик: «Нет, Ваша честь!». Судья: «Исполнитель, присуждаю — 2 года уборки снега в Сибири за невыполнение условий ТЗ!».

Формулировки должны быть «закрытыми», т.е. четко указывать границу нашей работы. В ТЗ не может быть написано «админка должна быть удобной». Удобство — субъективный фактор, кому-то удобно так, кому-то иначе, и в случае спора трудно будет установить, кто прав. Формулировка «админка должна быть удобной» может привести к бесконечным переделкам: «добавьте в админку к списку товаров сортировку по столбцам и фильтрацию. Без этого не удобно. И загрузку товаров из экселя, по одному добавлять не удобно».

«Всё, что не оговорено, выполняется на усмотрение исполнителя» — не смотря на суровость этого заявления, эта фраза должна присутствовать в ТЗ. Она проистекает из самой сути задания: заказчик хочет получить некий продукт, но он не может и не должен указывать каким образом будет достигнут конечный результат. Этот пункт защищает от вмешательства в глубины работы (не хватало, чтоб заказчик начал рассказывать, как именовать функции в коде и какие пакеты использовать), но также перечеркивает возможность заказчика иметь любые хотелки. На мой взгляд, стоит идти на встречу заказчику в хотелках, пока это не выходит за рамки приличия. Когда же терпение лопается, нам и пригодится этот пункт. Как в песне поется: «Мы мирные люди, но наш бронепоезд стоит на запасном пути». (Фразу «что не оговорено — на усмотрение исполнителя», лучше всунуть под конец ТЗ, в начале она может быть встречена в штыки. Но если ТЗ нормальное и в конце стоит эта фраза, против неё не будут протестовать).

Тех. задание — это документ, который нам дает заказчик (Не важно, что его пишем мы. По смыслу это задание, техническое задание, а задание дает заказчик исполнителю, т.е. нам). А из этого следует, что в ТЗ должны быть формулировки, которые указывают нам, что делать (типа «сайт должен содержать», «должна быть возможность»). В некоторых ТЗ я видел, формулировки вида «на сайте будет то-то и то-то» — это неверная формулировка, это какое-то уведомление заказчика, что будет сделано, но документ-то называется «задание», а не «уведомление».

3. Разделы ТЗ

3.1 Общие слова

Этот раздел вводит в курс дела. Исходите из того, что вам нужно отдать ТЗ стороннему программисту, и вас не будет на связи всё время работы над проектом вплоть до сдачи. Т.е. программист должен взять ТЗ, и у него не должно возникнуть ни одного вопроса, а первый вопрос, который он мог бы задать — это: «а про что сайт делать будем?» Раздел «Общие слова» в вольной форме и отвечает на этот вопрос.
3.2 Эксплуатационное. назначение

Коротко говоря, эксплуатационное назначение — это выгода, которую должен принести сайт. Вообще, чаще всего, выгода сводится к деньгам (если сайт как-то завязан на коммерции, а таких большинство), и в разделе можно было бы всегда ограничиться написанием того, что эксплуатационное назначение сайта — подзаработать деньжат, но мы не будем столь циничными. Остановимся на шаг раньше, непосредственно перед «подзаработать деньжат». Для интернет магазина это будет продажа товара (с которого мы получим деньги), для скидочного сайта это состыковать клиентов и продавцов или поставщиков услуг (чтоб с этого получить свой процент денег), для сайта визитки — это прорекламироваться в инете (а реклама нужна для получения денег) и т.д.
3.3 Функциональное назначение

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

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

3.4 Термины и определения

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

Во втором случае, как правило, не нужно описывать термины специфичные для предметной области, но не имеющие отношения к реализации проекта. Например, для магазина торгующего запчастями для парусных судов, не стоит выносить в термины такое, как стаксель и ванты. Здесь нужны расшифровки терминов, которыми оперирует заказчик и вкладывает в них некий смысл, который может быть нами истолкован неверно. Какие-то простые слова, но в данном контексте, принимающие особое значение. Например, заказчик говорит: «Сеанс работы с сайтом стоит 100 тугриков». Фраза «сеанс работы с сайтом» — претендент на описание. Этот термин может означать продолжительность времени от входа на сайт до выхода, или же период работы пока на счету пользователя не закончатся деньги. Т.е. нам нужно точно знать, что такое «Сеанс работы». Ошибочное понимание такого простого термина может создать реальную проблему.

3.5 Данные и списки

Ключевой раздел ТЗ. Можно сказать его сердце. Это не самый многословный, но самый важный и трудный пункт ТЗ. Если он сделан как надо, можно быть уверенным, что автор задания понимает, что именно нужно сделать. Наличие этого пункта накладывает очень сильные ограничения на создаваемый продукт. Один только этот пункт, думаю, «весит» больше половины всего ТЗ.

Данные

Этот раздел содержит перечень сущностей, которые используются в проекте. Это очень близко к описанию таблиц в базе данных или моделей, если говорить о фреймворках с MVC. Например, у нас на сайте есть новости. А что такое новость? Как гласит военное определение, куст — это совокупность веток и листьев торчащих из одного места. Так и новость, это совокупность заголовка, текста и даты публикации. Для чего нужно это определение? Как и всё в ТЗ — прояснить, что делать и подстраховаться от хотелок.

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

Для примера, та же самая новость:

  • Заголовок
  • Текст
  • Дата публикации

Предположим, в процессе работы выясняется, что забыли анонс новости (коротенький текст, который отображается в списке новостей). Добавить его не проблема: нужно в таблицу добавить поле «анонс» типа «текст» и дополнительное поле ввода в создании/редактировании новости. Доработка несложная.

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

Списки

Как подсказывает Кэп, новость — это новость, а список новостей — это список новостей.
Зачем это описывать? Допустим мы должны отобразить на главной странице «последние новости». Вот последние новости, это как раз такой список. А что есть «последние новости»? Это уже можно понять по разному, это могут быть последние 5 новостей, а может это новости за последние 24 часа? Приведенный пример прост, его недорого исправить и при сдаче проекта. Но есть более тяжелые случаи.

Например, заказчик хочет свой сайт с коллективными блогами, типа своего хабра. И он хочет, что бы на странице, где отображается одна статья, сбоку был список «похожих статей». Что такое похожие статьи? Этот вопрос требует отдельного разбирательства и описания. И не обратив внимания на этот список мы рискуем уже достаточно серьёзно. Т.е. тут нужно подробно описывать алгоритм по определению сходства статей. Пропустив этот пункт на этапе оценки сроков можно промахнуться достаточно сильно.

3.6 Страницы с описанием

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

Тут будет уместно описать не только, что отображается, но и как. Не в том смысле, что мы описываем дизайн: «Большими красными буквами отображается название новости», а в смысле, как работает: «Слева плавно выезжает окошко с предложением ввести логин и пароль». Или так: «при нажатии кнопки „Отправить комментарий“, комментарий появляется на странице без перезагрузки, с помощью AJAX».

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

Естественно, будет очень здорово добавить к каждой странице эскиз вроде такого:

Стоит следить, чтобы текстовое описание не вступало в противоречие с тем, что нарисовано в эскизе.
Т.е. если на иллюстрации новость имеет «Категорию новости», а в разделе «Данные и списки» новость не имеет ее, то это проблема. Очень высока вероятность, что изучая ТЗ, заказчик запомнит именно картинку с эскизом новостей, в которой есть категория, и если в готовом проекте не будет категории (в соответствии с текстовым описанием новости), он расстроится.

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

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

3.7 Требования к надежности

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

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

3.8 Требования к хостингу

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

Помимо таких очевидных проблем есть проблемы и потоньше. Например, для нормальной работы нужен cron, а хостер его не предоставляет (абсолютно реальный случай из моей практики). Или, скажем, специфический сайт, который не может работать на shared хостинге, ему нужен только VPS или VDS.

Сюда стоит включить требования к интерпретаторам, библиотекам, пакетам, гемам, требования к дисковому пространству, памяти, smtp, pop, ftp, внешним программам и прочему, что имеет значение для работы проекта.

3.9 Наполнение контентом

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

Если мы должны, например, залить в каталог 500 фотографий, предварительно их обработав, то это следует описать именно тут.

Описание этого раздела предостережет нас от разного понимания того, кто должен залить 500 фотографий и наполнить каталог товарами.

3.10 Сдача и приемка

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

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

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

Заключение

Конечно, это ТЗ не охватывает все стороны сайта, но для очень большого числа проектов оно станет хорошим описанием.

Да, это ТЗ имеет пробелы, например, не сказано, как быть если у сайта должно быть API. Однако, имея хороший раздел «данные и списки», расширить ТЗ на эту область будет достаточно просто.

Буду рад услышать критику и, особенно, описание случаев, когда подобное ТЗ не подходит.

Разработка технического задания на сайт

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

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

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

Общие рекомендации

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

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

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

Убедитесь, что ваш TT не содержит расплывчатых описаний, слов-заполнителей и ненужных фраз. .Документ не должен содержать абстрактных инструкций, таких как «четкая и простая навигация». Отсутствие конкретики, пунктуационные ошибки и обилие лишних слов могут исказить смысл и усложнить понимание задач в целом, поэтому будьте с этим особенно осторожны.

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

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

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

Примерный состав технического задания

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

  1. Общая информация
  2. Глоссарий
  3. Функциональные требования
  4. Описание страниц и модулей
  5. Функциональные характеристики
  6. Системные требования администратора
  7. Хостинг и перенос сайта
  8. Резервное копирование и надежность
  9. Общая информация

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

    Глоссарий

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

    Функциональные требования

    Здесь мы описываем, какими техническими инструментами и функциями должен обладать сайт. В первую очередь, речь идет о требованиях к структуре, классам пользователей и т. Д. Например, если вы создаете обычный информационный бизнес-сайт, то вам нужно перечислить основные страницы: «О компании», «Наши услуги», «Контакты» + форма обратной связи.Если, например, разрабатывается интернет-магазин, этот раздел будет намного обширнее и сложнее.

    Описание страниц и модулей

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

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

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

Функциональные характеристики

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

Системные требования администратора

Сюда входит информация об административной панели, возможностях управления сайтом и системах CRM (если они будут использоваться).

Хостинг и перенос сайта

В этом разделе описана процедура переноса разработанного сайта на оборудование заказчика. Также указывается, кто и как обеспечивает соответствие программно-аппаратной платформы требованиям проекта.

Резервное копирование и надежность

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


Читайте также: Кто такие лендинги?


И еще одно

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

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

Удачи в ваших проектах!

.

5 шагов к созданию технической документации, которая (на самом деле) полезна

Джори Маккей

Джори - писатель, контент-стратег и отмеченный наградами редактор книги Unsplash. Он вносит свой вклад в Inc., Fast Company, Quartz и другие.

15 ноября 2018 г. · 11 мин чтения

🎁 Бонусный материал: шаблон технической документации



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

Напишите свой? Вот бесплатный шаблон и контрольный список!

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

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

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

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

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

Но сначала краткий обзор этой статьи:

Когда, почему и как правильно использовать техническую документацию

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

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

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

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

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

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

Итак, как же создать эти четкие, краткие и удивительно полезные документы?

Напишите свой? Вот бесплатный шаблон и контрольный список!

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

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

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

Шаг 1: Проведите исследование и создайте «План документации»

Как гласит старая пословица: «Напишите то, что вы знаете».

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

Если вы не являетесь экспертом в предметной области, это может означать проведение некоторых внутренних собеседований и налаживание отношений с технической командой, чтобы лучше понять материал (и избежать того, что старший технический писатель Уилл Келли называет техническим «Миссия невыполнима». написание проектов).Или это может быть так же просто, как просмотреть существующие ресурсы и руководства и провести краткий аудит того, что у вас есть, а что отсутствует.

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

  • Цели: Проще говоря, что вы хотите, чтобы люди могли делать? Это для использования вашего продукта? Находите справочные документы быстро и легко? Узнайте, как использовать определенные аспекты вашего инструмента? Разрешить товарищам по команде запрашивать ресурсы или заказывать оборудование? Наличие и знание четкой цели необходимо для написания хорошей технической документации и поможет информировать обо всем, что вы делаете.
  • Существующие ресурсы: Что сейчас доступно? Вы обновляете или объединяете текущие ресурсы или начинаете с нуля? Есть ли старые, устаревшие версии, которые нужно убить? Сделайте быстрый аудит и найдите все, что поможет вам писать или запутать аудиторию, если они это найдут.
  • Руководства по стилю: В некоторых отраслях требуется, чтобы вы писали техническую документацию определенным образом (например, рекомендации на простом языке для правительственных сайтов или упрощенный технический английский для аэрокосмических, авиационных или оборонных компаний).В других случаях у вашей компании может быть руководство по стилю, в котором объясняется, какой язык использовать, как разговаривать с пользователями и даже грамматические стили.
  • Описание тем: Какие темы и подтемы вы будете освещать в своей технической документации? Думайте об этом как о содержании и попытайтесь перечислить все основные разделы и подразделы, которые, по вашему мнению, вам понадобятся.
  • Инструменты и управление: Какое программное обеспечение, инструменты или веб-сайты будут использоваться для создания и управления документацией? Ссылка на соответствующие руководства по стилю.
  • Срок и окончательные результаты: Когда он должен быть и в каком формате он будет? Техническая документация касается не только содержания, но и структуры и доставки. А знание того, как будет представлен контент, перед тем, как вы начнете, расскажет вам, что вам нужно и куда приложить усилия.

Шаг 2: Структура и дизайн

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

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

Вот несколько быстрых советов для каждого:

Используйте шаблоны или «схемы» для согласованного дизайна на странице

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

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

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

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

  • Название: Что это?
  • Подзаголовок: Дополнительная информация
  • Обзор : Что вы узнаете
  • Содержание: Внутренняя навигация
  • Функции: Каждый раздел документа
  • Читать далее: Связанные документы, которые могут помогите пользователю

Вот пример использования Planio wikis:

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

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

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

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

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

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

Шаг 3. Создайте контент

Хорошо! Имея план документации и структуру , пора серьезно заняться созданием технической документации.

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

Начните с черновика

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

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

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

Несколько простых советов по хорошему письму:

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

  1. Пишите как человек : используйте простой, ясный язык, когда это возможно. Мы все читали те документы, которые звучат так, будто Google Translate пошел не так, как надо. Если вы замечаете, что произносите неловкие предложения или сложный язык, отойдите на несколько минут. Иногда возвращение к письму после короткого перерыва - это все, что нужно, чтобы освежить сознание.
  2. Помните, ваши читатели - это не вы: Золотая заповедь технического письма - , не принимайте . Вам может показаться, что вы слишком очевидны, но вы должны четко осознавать уровень знаний вашей аудитории. Не думайте, что они знают даже наполовину меньше вас.
    Золотая заповедь технического письма - «не предполагай». Вам может казаться, что вы слишком очевидны, но вы должны осознавать уровень знаний вашей аудитории.
  3. Напишите столько, сколько нужно, чтобы быть полезным, и ни слова больше: Короткое письмо - хорошее письмо.Используйте форматирование, чтобы разбивать большие фрагменты текста и сохранять четкость в центре внимания. Как пишет технический писатель Amazon Том Джонсон: «Хороший технический писатель сокращает количество слов до нужной краткости, не делая ничего неясного».
  4. Помните о силе визуальных эффектов: Это еще одно клише, но изображения действительно говорят тысячу слов. По возможности визуализируйте то, что вы говорите, а не пытайтесь это объяснить.

Используйте правило 30/90, чтобы получить обратную связь

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

Если вы не являетесь экспертом в той теме, о которой пишете, неплохо было бы, чтобы эксперт по предмету (SME) пришел на рассмотрение после первого и окончательного черновиков. Обратная связь - это уже само по себе умение. Что касается технической документации, то один из лучших способов ее оформления - это то, что Джейсон Фридман называет «обратной связью 30/90».

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

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

Получите экспертные оценки и внесите исправления

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

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

Редактировать, редактировать и еще раз редактировать

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

Вики-сайты Planio особенно эффективны для редактирования с контролем версий, историей, ролями и разрешениями, чтобы вы и ваша команда всегда были в курсе того, кто что написал и что редактировал.

Вики-сайты Planio особенно эффективны для редактирования с контролем версий, историей, ролями и разрешениями, чтобы вы и ваша команда всегда были в курсе того, кто что написал и что редактировал.

Шаг 4: Доставка и тестирование

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

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

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

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

Наконец, проверяет удобство использования / проблемы с UX . Пользователи теряются или сбиваются с толку? Разве они не получают ответы, которые искали (или думали, что получали на основе заголовков или навигации?). Опыт пользователя сводится к большему, чем просто то, что вы написали. Найдите время поработать со сторонними тестировщиками, чтобы убедиться, что, когда реальные пользователи приходят к вашим документам, они уходят довольными.

Шаг 5. Составьте график обслуживания и обновления

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

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

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

4 дополнительных качества отличной технической документации

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

  1. Эффективность разработки и использования: Дублированный контент, неорганизованная структура и нечеткие процессы могут убить техническую документацию. Используйте такой инструмент, как wikis от Planio, чтобы сохранять организованный и эффективный контент.
  2. Актуальная информация: Нет смысла предоставлять пользователям неточную информацию или показывать им устаревшие скриншоты, которые не похожи на то, с чем они имеют дело.Поддерживайте актуальность вашей технической документации.
  3. Единый дизайн и структура: Каждый раз, когда вы вступаете в контакт с вашими пользователями, наступает время для создания вашего бренда. Придерживайтесь своего дизайна, стиля и тона во всей онлайн-документации.
  4. Доступен где угодно : Мобильная связь захватывает мир. Ваша техническая документация, как и остальная часть вашего веб-сайта или приложения, должна быть гибкой и обеспечивать удобство для пользователей на всех устройствах.

Технические документы могут воодушевить или расстроить - выбор за вами

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

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

Напишите свою собственную техническую документацию, используя наш шаблон!

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

.

Задачи технического письма

Марк Никол

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

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

Техническое написание выполняется с учетом различных соображений:

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

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

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

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

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

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

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

Хотите улучшить свой английский за пять минут в день? Получите подписку и начните получать наши ежедневные советы и упражнения по написанию!

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

Прекратите делать эти досадные ошибки! Подпишитесь на Daily Writing Tips сегодня!

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

Управление проектами - Написание пользовательских историй для внутренних технических задач

Переполнение стека
  1. Около
  2. Товары
  3. Для команд
  1. Переполнение стека Общественные вопросы и ответы
  2. Переполнение стека для команд Где разработчики и технологи делятся частными знаниями с коллегами
  3. Вакансии Программирование и связанные с ним технические возможности карьерного роста
  4. Талант Нанимайте технических специалистов и создавайте свой бренд работодателя
.

Смотрите также

Поделиться в соц. сетях

Опубликовать в Facebook
Опубликовать в Одноклассники
Вы можете оставить комментарий, или ссылку на Ваш сайт.

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