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

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

Кардинальным образом ситуация изменилась после того, как я прошел курс HowToCode^{[ссылка удалена модератором, т.к. нарушает правила]}. В курсе описан системный и, как всё гениальное, простой и красивый подход к разработке, который сводит воедино анализ, проектирование, документацию, тестирование и разработку кода. Весь курс построен на использовании функциональной парадигмы и языка Scheme (диалекта Lisp), тем не менее, рекомендации вполне применимы и для других языков, а для JavaScript и TypeScript, к которым я постарался их адаптировать, так и вообще подходят отлично.

Результаты мне очень понравились:

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

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

• В-третьих, я практически избавился от отладки: того самого процесса, когда код уже написан, но ещё не работает или работает не так как надо, чем дико раздражает

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

• Да, и, предвидя вопросы, скажу - по ощущениям время разработки если и замедлилось, то не сильно, даже с учётом написания тестов и документации. А экономия на поддержке кода - просто колоссальная.

Но давайте уже перейдём к сути и посмотрим, как этот подход устроен.

Общая идея

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

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

Этапы проектирования

Подход включает 3 этапа:

1. Анализ задачи и предметной области

2. Проектирование структур данных

3. Проектирование функций

Анализ задачи и предметной области

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

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

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

Процедура анализа задачи

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

Алгоритм

В общем виде алгоритм выглядит так:

Шаг 1. Представить задачу в динамике

Шаг 2. Выделить константы, переменные и события.

Шаг 1. Представить задачу в динамике

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

• в исходном состоянии

• в различных промежуточных состояниях: возможно, появляется загрузка, или раскрываются какие-то списки или открываются какие-то окна

• при окончании работы

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

Пример

Допустим, первоначальная постановка задачи звучала как: "Реализовать для web-портала раскрывающийся список, который бы показывал перечень сотрудников, входящих в учебную группу. Для каждого сотрудника должно быть указано ФИО и дата его рождения."

Звучит неплохо, но что делать, пока ещё непонятно. Берем карандаш, бумагу и, если есть возможность, самого заказчика и начинаем рисовать (Ну а я буду рисовать в редакторе).

Начальное состояни

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

Промежуточные состояния

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

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

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

Шаг 2. Выделить константы, переменные и события

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

Константы

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

• оформление: цвета, шрифты, расстояния, логотипы и иконки, размеры сетки и экрана и т.д.

• сетевые данные, например, адреса серверов,

• строковые константы: названия, заголовки и т.п.

Пример выделения констант

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

• Адрес сервера, с которым работает наше приложение

• Название приложения, которое отображается в виде заголовка

• Оформление

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

Переменные

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

• координаты объектов

• значения таймера

• различные переменные, отражающие состояние элементов интерфейса и т.д.

Пример выделения переменных

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

У меня получился следующий список:

• Состояние загрузки приложения: загружается или данные уже загружены

• Группа, для описания которой нам, скорее всего, понадобится её идентификатор, название, статус открытия списка группы

• Список участников группы, который, наверняка, в будущем будет являться свойством группы

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

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

События

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

Событиями могут быть:

• Изменения этапов жизненного цикла приложения или его отдельных компонентов: инициализация, обновление, удаление, и т.п.

• Пользовательский ввод: события мыши или клавиатуры

• Таймер

• Получение данных с сервера и т.д.

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

• загрузка данных приложения и

• открытие и закрытие списка сотрудников по клику мыши на шапку группы

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

Теперь мы уже существенно продвинулись вперед:

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

2. Во-вторых, мы сделали её куда как более конкретной, свели все возможные варианты реализации списков к одному

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

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

Проектирование структуры данных

Теперь мы можем переходить ко второму этапу нашего алгоритма - проектированию структур данных.

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

Назначение

Для чего нам это надо?

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

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

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

Алгоритм

Структуры мы описываем в следующем порядке:

1. Фиксируем название структуры

2. Описываем её тип

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

4. Придумываем один - два примера заполненной структуры.

На этом этапе уже начинают играть роль используемые технологии. В нашем случае появляются TypeScript и JSDoc, но для других языков и платформ вполне может использоваться и что-то другое. Ну а раз мы говорим о веб-разработке и библиотеке React JS, то надо сразу отметить, что мы дальше будем использоваться понятия свойств (props) и состояний (state), характерных для React. Ничего страшного, если вы с этими понятиями не знакомы, думаю, что всё будет и так понятно.

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

Пример

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

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

Фиксируем название структуры. Название должно отражать суть структуры. В нашем случае, назовём её AppState - состояние приложения:

export interface AppState {}

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

Фиксируем это в коде:

export interface AppState {        title: string;        backendAddress: string;    isLoading: boolean;    group?: Group;    loadData: Function;}

Пишем интерпретацию структуры

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

/** * Общее состояние приложения * @prop title - заголовок приложения * @prop backendAddress - адрес сервера * @prop isLoading - флаг загрузки данных (true - загружаются, false - загружены) * @prop group - данные об отображаемой группе. На момент загрузки данных group не определена * @method loadData - метод загрузки данных */export interface AppState {    title: string;    backendAddress: string;    isLoading: boolean;    group?: Group;    loadData: Function;}

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

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

/** * Общее состояние приложения * @prop title - заголовок приложения * @prop backendAddress - адрес сервера * @prop isLoading - флаг загрузки данных (true - загружаются, false - загружены) * @prop group - данные об отображаемой группе. На момент загрузки данных group не определена * @method loadData - метод загрузки данных */export interface AppState {    title: string;    backendAddress: string;    isLoading: boolean;    group?: Group;    loadData: Function;}/** * Данные об отображаемой группе*///TODOexport interface Group {}

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

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

/** * Общее состояние приложения * @prop title - заголовок приложения * @prop backendAddress - адрес сервера * @prop isLoading - флаг загрузки данных (true - загружаются, false - загружены) * @prop group - данные об отображаемой группе. На момент загрузки данных group не определена * @method loadData - метод загрузки данных */export interface AppState {    title: string;    backendAddress: string;    isLoading: boolean;    group?: Group;    loadData: Function;}//Пример 1const appState1: AppState = {    title: "Заголовок 1",    backendAddress: "/view_doc.html",    isLoading: true,    group: undefined,    loadData: () => {}}//Пример 2const appState2: AppState = {    title: "Заголовок 2",    backendAddress: "/view_doc_2.html",    isLoading: false,    group: group1, //Заглушка для вложенной структуры    loadData: () => {}}/** * Данные об отображаемой группе*///TODOexport interface Group {}//TODOconst group1 = {}

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

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

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

export default abstract class AbstractService {           /**     * Метод загрузки данных о группе с сервера     * @fires get_group_data - имя действия, вызываемого на сервере     * @returns данные о группе     */    abstract getGroupData(): Promise<Group>;}

На клиенте останется только реализовать этот класс, а на сервере - реализовать нужные действия и отдавать данные, которые сервис ожидает, формат их уже для всех ясен.

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

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

Только теперь мы, наконец, переходим к разработке.

Как и для других этапов, для проектирования функций у нас есть свой рецепт - алгоритм:

Алгоритм первоначального проектирования функций

1. Создаем заглушку. Заглушка - это определение функции, которое:

   • отражает правильное название функции

   • принимает правильное количество и типы параметров

   • возвращает произвольный результат, но корректного типа

2. Описываем входные, выходные данные и назначение функции

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

4. Пишем тело функции.

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

   1. сразу описываем функцию и добавляем заглушку

   2. добавляем отметку (TODO), помечающую нашу функцию как объект списка задач

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

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

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

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

Шаг 1 - Создаем заглушку

Заглушка функции - это минимальное работоспособное её описание, в котором есть:

• правильное название функции,

• правильное количество и тип параметров и

• возвращаемое значение, произвольное по содержанию, но правильного типа.

Для простой функции на TypeScript будет вполне достаточно написать что-то вроде:

export const getWorkDuration = (worktimeFrom: string, worktimeTo: string): string => {    return "6ч 18мин";}

где:

• getWorkDuration - правильное название фукнции, то есть то, которое мы и дальше будем использовать

• worktimeFrom: string, worktimeTo: string - два строковых параметра. Именно столько параметров и такого типа функция должна принимать

• : string после закрывающей круглой скобки - тип возвращаемого значения

• return "6ч 18мин" - возврат произвольного значения, но правильного типа из функции

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

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

Для функциональных компонентов:

const componentName = (props: PropsType) => { return <h1>componentName</h1> }

Для компонентов классов:

class componentName extends React.Component<PropsType, StateType>{    state = {        //произвольные значения для всех обязательных свойств состояния    }    render() {                return <h1>componentName</h1>     }}

где:

• PropsType - это описание типа передаваемых свойств

• StateType - описание типа состояния компонента

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

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

interface AppProps {}export default class App extends Component<AppProps, AppState> {    state = {        title: "Отображение списка групп",        backendAddress: "",        isLoading: true,        loadData: this.loadData.bind(this)    }    /**     * Метод загрузки данных с сервера     */    //TODO    loadData() {    }    render() {        return <h1>App</h1>    }}

Надо отметить пару особенностей этой реализации:

1. В компонент App не передаётся никаких свойств "сверху", поэтому интерфейс AppProps пустой

2. Тип состояния компонента AppState мы импортируем напрямую из описания типов, которое мы создали, когда проектировали структуры

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

Шаг 2 - Описываем входные и выходные данные

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

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

/** * Рассчитывает количество часов и минут между указанным начальным и конечным временем * Если время начала работы больше времени конца, то считается, что конечное время - это время следующих суток * @param worktimeFrom - время начала работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @param worktimeTo - время конца работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @return количество часов и минут между переданным временем в формате Хч Y?мин, например 6ч 18мин или 5ч, если количество часов полное *///TODOexport const getWorkDuration = (worktimeFrom: string, worktimeTo: string): string => {    return "6ч 18мин";}

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

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

Шаг 3. Тестирование

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

• unit-тесты должны, как минимум, один раз проходить по каждой ветке внутри функции - то есть проверять все ветвления, если они есть

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

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

Последний пункт надо пояснить отдельно. Для этого давайте посмотрим, как это работает в функциональном программировании.

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

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

Допустим, у нас есть структура данных, описывающая состояние светофора. Эта структура называется "перечисление" или enum. То есть переменная этого типа может находиться в нескольких дискретных значениях:

type TrafficLights = "красный" | "желтый" | "зеленый";

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

function trafficLightsFunction (trafficLights: TrafficLights) {    switch (trafficLights) {        case "красный":            ...        case "желтый":            ...        case "зеленый":            ...    }}

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

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

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

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

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

Примеры тестов

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

/** * Рассчитывает количество часов и минут между указанным начальным и конечным временем * Если время начала работы больше времени конца, то считается, что конечное время - это время следующих суток * @param worktimeFrom - время начала работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @param worktimeTo - время конца работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @return количество часов и минут между переданным временем в формате Хч Y?мин, например 6ч 18мин или 5ч, если количество часов полное *///TODOexport const getWorkDuration = (worktimeFrom: string, worktimeTo: string): string => {    return "6ч 18мин";}

Итак, функция расчёта рабочего времени. Пусть вас не смущает тип string у параметров, каждый из параметров - это время, представленное в виде строки ЧЧ:ММ, то есть не атомарный тип, а интервал от 00:00 до 23:59. Согласно таблице, для интервалов надо проверить граничные значения и значения внутри диапазона. А так как параметра два, то это справедливо для каждого из них. Для этого нам потребуется 3 тест-кейса:

1. Первый параметр выходит за граничное значение, а второй нет

2. Второй параметр выходит за граничное значение, а первый - нет

3. Оба параметра - в пределах нормальных значений

И ещё в документации есть отметка о том, что рабочее время считается по разному в зависимости от соотношения значений. Вместо одного тест-кейса, где параметры находятся в пределах нормы, напишем 3 кейса, где первый параметр меньше, больше и равен второму, итого 5

Тест-кейсы мы к тому же составили так, чтобы одновременно проверялись выводимые значения: с минутами и без. Остается только написать сами тесты. Я их пишу при помощи Jest и Enzyme - стандартной комбинации для React JS. В самом написании тестов особых премудростей нет, поэтому приведу только один пример:

describe('Тестирование расчёта времени между началом и концом работы', () => {        it('Когда начало и конец смены совпадают, функция возвращает 0ч', ()=>{        const result = getWorkDuration("01:32", "01:32");        expect(result).toBe("0ч");    });        //Подобным образом описываем все сценарии    ...});

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

Давайте протестируем компонент App. Заглушка для него выглядела следующим образом:

interface AppProps {}export default class App extends Component<AppProps, AppState> {    state = {        title: "Отображение списка групп",        backendAddress: "",        isLoading: true,        loadData: this.loadData.bind(this)    }    /**     * Метод загрузки данных с сервера     */    //TODO    loadData() {    }    render() {        return <h1>App</h1>    }}

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

/** * Общее состояние приложения * @prop title - заголовок приложения * @prop backendAddress - адрес сервера * @prop isLoading - флаг загрузки данных (true - загружаются, false - загружены) * @prop group - данные об отображаемой группе. На момент загрузки данных group не определена * @method loadData - метод загрузки данных */export interface AppState {    title: string;    backendAddress: string;    isLoading: boolean;    group?: Group;    loadData: Function;}

Для начала определимся, к какому типу данных относится эта структура:

• Во-первых, это сложная структура, состоящая из нескольких полей и членов.

• Во-вторых, среди полей есть зависимые. Так, наличие поля group зависит от состояния загрузки, пока данные не загружены, данных о группе - нет. Если есть зависимые данные, то можно смело относить эти данные к типу "Детализация".

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

• для сложных типов (объектов) нужно написать как минимум 2 теста, изменяя при этом значения полей

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

Таким образом, нам следует написать 4 отдельных теста:

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

• 2 - изменяя статус загруженности и соответствующие данные, чтобы проверить, правильность поведения компонента в этом случае

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

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

Начнём с простого - с вызова метода loadData при загрузке компонента:

import React from 'react';import Enzyme, { mount, shallow } from 'enzyme';import Adapter from 'enzyme-adapter-react-16';Enzyme.configure({ adapter: new Adapter() });import App from './App';describe('App', () => {    test('Когда компонент App смонтирован, вызывается функция loadData', () => {        //Добавляем слушателя к функции loadData        const loadData = jest.spyOn(App.prototype, 'loadData');                //Монтируем компонент        const wrapper = mount(<App></App>);                //Проверяем количество вызовов функции loadData        expect(loadData.mock.calls.length).toBe(1);    });}

Здесь мы подключили enzyme к нашему файлу с тестами, импортировали сам компонент и написали первый тест. Внутри теста мы:

1. добавили слушателя к функции loadData внутри компонента,

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

3. проверили, что компонент в ходе монтирования вызвал нашу функцию загрузки данных

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

test('Когда данные загружаются, отображаются только заголовок и спиннер', () => {        //Монтируем компонент        const wrapper = mount(<App></App>);        //Подменяем состояние компонента на нужное для тестирования        wrapper.setState({            title: "Заголовок 1",            backendAddress: "/view_doc.html",            isLoading: true,            group: undefined,            loadData: () => {}        })        //Проверяем правильность отображения компонента        //Проверяем наличие и содержание заголовка        expect(wrapper.find('h1').length).toBe(1);        expect(wrapper.find('h1').text()).toBe("Заголовок 1");        //Заглушка, отображающаяся в процессе загрузки        expect(wrapper.find(Spinner).length).toBe(1);        //Компонент, отображающий группу отображаться не должен        expect(wrapper.find(Group).length).toBe(0);    });

Этот сценарий мы реализуем по следующей схеме:

1. Монтируем компонент

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

3. Проверяем правильность отображения компонента

Пока мы писали тест, стало понятно, что для нашего приложения потребуются ещё 2 компонента, которые мы пока не реализовывали:

• заглушка для отображения в процессе загрузки - спиннер и

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

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

Реализуем третий сценарий по аналогичной схеме:

test('Когда данные загружены, отображается заголовок и группа. Спиннер не отображается', () => {        const wrapper = mount(<App></App>);        wrapper.setState({            title: "Заголовок 2",            backendAddress: "/view_doc_2.html",            isLoading: false,            group: {                id: "1",                name: "Группа 1",                listOfCollaborators: []            },            loadData: () => {}        })        expect(wrapper.find('h1').length).toBe(1);        expect(wrapper.find('h1').text()).toBe("Заголовок 2");        expect(wrapper.find(Spinner).length).toBe(0);        expect(wrapper.find(Group).length).toBe(1);    });

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

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

Шаги 4 и 5. Реализация функций и формирование списка задач

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

• во-первых, старайтесь писать более высокоуровневый код,

• во-вторых, избегайте коварной ошибки, которая называется Knowledge Shift (сдвиг области знаний).

Высокоуровневый код

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

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

/** * Рассчитывает количество часов и минут между указанным начальным и конечным временем * Если время начала работы больше времени конца, то считается, что конечное время - это время следующих суток * @param worktimeFrom - время начала работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @param worktimeTo - время конца работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @return количество часов и минут между переданным временем в формате Хч Y?мин, например 6ч 18мин или 5ч, если количество часов полное *///TODOexport const getWorkDuration = (worktimeFrom: string, worktimeTo: string): string => {    return "6ч 18мин";}

Очевидно, что для того, чтобы получить разницу во времени между двумя параметрами, каждый из которых представляет собой строку в формате "ЧЧ:ММ", и вернуть эту разницу тоже в строковом формате, нам надо выполнить несколько действий:

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

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

3. Привести получившуюся разницу к формату Xч Y?мин, который и вернуть из функции

И тут мы могли бы пойти двумя путями:

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

• выделить каждый шаг в отдельную функцию.

В результате мы бы получили такую картину:

/** * Рассчитывает количество часов и минут между указанным начальным и конечным временем * Если время начала работы больше времени конца, то считается, что конечное время - это время следующих суток * @param worktimeFrom - время начала работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @param worktimeTo - время конца работы в формате ЧЧ:ММ (от 00:00 до 23:59) * @return количество часов и минут между переданным временем в формате Хч Y?мин, например 6ч 18мин или 5ч, если количество часов полное */export const getWorkDuration = (worktimeFrom: string, worktimeTo: string): string => {    const worktimeFromInMinutes = getWorktimeToMinutes(worktimeFrom);    const worktimeToInMinutes = getWorktimeToMinutes(worktimeTo);    const minutesDiff = calcDiffBetweenWorktime(worktimeFromInMinutes, worktimeToInMinutes);    return convertDiffToString(minutesDiff);}/** * Вычиcляет количество минут, прошедших с начала суток * @param worktimeFrom - время в формате ЧЧ:ММ (от 00:00 до 23:59) * @returns количество минут, прошедших с 00ч 00минут *///TODOexport const getWorktimeToMinutes = (worktime: string): number => {    return 0;}/** * Вычисляет количество минут между началом и концом рабочего дня с учётом суток * @param worktimeFrom - время начала рабочего дня в виде количества минут, прошедших с начала суток * @param worktimeTo - время конца рабочего дня в виде количества минут, прошедших с начала суток * @returns количество минут между началом и концом рабочего дня с учётом суток *///TODOexport const calcDiffBetweenWorktime = (worktimeFrom: number, worktimeTo: number): number => {    return 0;}/** * Преобразовывает количество минут во время в формате Хч Y?мин * @param minutes - количество минут * @returns время в формате Хч Y?мин, например 6ч 18мин или 5ч *///TODOexport const convertDiffToString = (minutes: number): string => {    return "6ч 18мин";}

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

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

Knowledge Shift

Говоря о проектировании функций, конечно же, нельзя обойти стороной такую ошибку как Knowledge Shift.

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

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

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

Чтобы этого избежать, рекомендуется передавать обработку внутренних сложных структур в отдельные функции, как мы сделали это при реализации нашего реакт-компонента App:

export default class App extends Component<AppProps, AppState> {    state = {        title: "Отображение списка групп",        backendAddress: "",        isLoading: true,        group: undefined,        loadData: this.loadData.bind(this)    }    /**     * Метод загрузки данных с сервера     */    //TODO    loadData() {}    componentDidMount() {        //Вызываем метод loadData при загрузке приложения        this.loadData();    }    render() {        const {isLoading, group, title} = this.state;        return (            <div className="container">                <h1>{title}</h1>                {                    isLoading ?                    <Spinner/>                    //Структуру типа Group передаем на обработку отдельному компоненту                    : <Group group={group}></Group>                }            </div>        );    }}

Мы добавили в компонент реализацию метода жизненного цикла componentDidMount, который вызовет наш метод загрузки данных при отображении компонента. Но основной функционал у нас содержится в методе render. В нем мы выводим заголовок и, в зависимости от статуса загрузки, рисуем либо заглушку - спиннер, либо компонент Group.

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

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

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

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

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

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

Про меня и мою базу знаний

В людях живал свету видал: топор на ногу обувал, топорищем подпоясывался

Ahoj. Меня зовут Коля, я QA тимлидер в компании Veeam. QA в нашей компании включает в себя не только тестирование, но и обеспечение качества в самом широком смысле. И среди этих смыслов затесалась такая штука, как управление знаниями. Я занимаюсь внутренней корпоративной базой знаний компании практически с самого ее появления, при этом поддержка базы знаний не входит в список моих обязанностей: это скорее что-то вроде pet-проекта. Долгое время у вики был статус поделочки, а мои попытки навязать вики коллегам приводили лишь к пополнению корпоративного стикер-пака моей фотографией.

Впрочем, время идет, времена меняются. Сейчас вики насчитывает 700 пользователей, 11 000 страниц, 56 000 правок и 688 000 слов (примерно полтора романа "Война и мир", если говорить только о тексте). Всего-то в 2 000 раз меньше русскоязычной Википедии, и это при условии работы на исключительно добровольных началах: никто не принуждает сотрудников пользоваться нашей вики.

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

Общий подход

Ищи себе прибыли, а другому не желай гибели

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

Главный совет, который я бы хотел дать в этой статье, звучит так: относитесь к проекту базы знаний как к публичному проекту. Скажем, если бы вы придумали Википедию или Хабрахабр, как бы вы продвигали их в массы? Реклама? Уникальный контент? Холодные как хвост вашей бывшей звонки на случайные номера из телефонной книги? Возможны любые варианты продвижения, но не забывайте адаптировать их к реалиям вашей компании и вашего коллектива. А еще не забывайте, что в случае недобросовестной рекламы коллеги узнают, где вас найти. Не перегибайте палку.

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

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

Собирайте статистику

Красна птица перьями, а человек знанием

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

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

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

• Анализ поисковых запросов решает сразу несколько проблем:

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

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

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

Накопите критическую массу знаний

Там хорошо, где нас нет

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

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

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

Еще один очевидный источник контента ваши личные заметки и ваши личные знания. Об этом аспекте давайте поговорим поподробнее.

Вам надо вот сами и пользуйтесь

Не ищи в селе, а ищи в себе

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

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

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

Сделайте вики единой точкой доступа для поиска любых знаний

И чтец, и жнец, и на дуде игрец

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

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

• Или же можно идти по пути Гугло-поисковика и встраивать себе поиск по другим сайтам. При этом необязательно писать свой краулер, можно обойтись и более дешевым решением. Например, воспользоваться поисковым API сторонних сайтов и выводить результаты поиска по другим сайтам, если на вашей вики результатов не нашлось.

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

Создавайте зону комфорта для окружающих

Не хвались теплом в нетопленой избе

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

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

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

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

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

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

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

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

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

  Конечно, остается проблема с тем, что одно и то же слово может означать сразу несколько вещей (скажем, "бекап" это резервная копия, задание резервного копирования, процесс резервного копирования, продукт Veeam Backup & Replication или отдел Backup QA в зависимости от контекста). Это пока что решаем по аналогии с Википедией: создаем страницу с термином и расписываем, что этот термин может значить.

• На большой Википедии вместе с каждой страничкой создается страница для обсуждения. Я же со своей вики все страницы обсуждения убрал: на мой взгляд, реализация дискуссий на Википедии очень плохо подходит для внутрикорпоративных дискуссий. Куда лучше заставить людей пользоваться привычными средствами ведения дискуссий: почта, чаты и звонки в MS Teams. И вопрос решается быстрее, и негатива меньше.

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

Рассказывайте о новостях

Из серебряных речей пулю не отольешь

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

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

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

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

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

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

Угрозы, вымогательства

Воруй любовь, убивай скуку

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

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

  Расскажите про пресловутый bus factor и проиллюстрируйте примером, ведь наверняка вы с этим уже сталкивались на практике (надеюсь, впрочем, что не в такой трагичной форме).

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

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

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

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

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

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

Играйте на здоровом самолюбии

Птицу кормом, а человека серебряной пулей обманывают

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

• Добавьте блок новостей на главную страницу, где будет информация обо всех новых правках (или хотя бы обо всех новых статьях). Рядом с именем статьи непременно должен светиться ник автора правки.

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

• У меня не было столько времени, чтобы добавлять геймификацию, но я добавил блок "Your impact" на главную страницу. Там выводится 10 самых просматриваемых статей из числа отредактированных вами, а рядом с ними число просмотров с момента вашей первой правки.

  Идея эта не моя, я подсмотрел ее на MediaWiki хакатоне в Праге, где growth team рассказывали про свои исследования аналогичной фичи большой Википедии и предлагали поучаствовать в разработке. Конечно, мне пришлось переписать фичу с нуля, поскольку у меня совсем другие источники данных, чем у Wikipedia, но в остальном я старался следовать рекомендациям Growth team.

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

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

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

Присматривайте за другими

У семи нянек детеныш без серебряной пули

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

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

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

Вместо заключения или "насильно мил не будешь"

Лучше на гривну убытку, чем на алтын стыда

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

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

Пожелание "сделайте так, чтобы мою вики использовали, пожалуйста" мало чем отличается от "сделайте так, чтобы в мою игру играло много человек". Да, у продвижения разных сервисов и услуг есть свои особенности, но у них гораздо больше общего, чем может показаться. Чтобы продвигать базу знаний, попробуйте мыслить как SMM специалист и основатель стартапа в одном лице, а не как Пётр I, насильно сбривающий бороды (никаких претензий к Петру, просто подход другой). И хотя идеального способа продвижения нет и вероятно, никогда не появится, в ваших силах найти рабочие для вашей конкретной компании способы. Удачи!

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

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

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

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

Зачем писать

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

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

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

Что писать

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

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

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

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

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

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

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

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

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

   

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

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

   

3. Глоссарий

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

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

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

   

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

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

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

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

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

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

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

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

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

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

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

   

9. Описание АПИ

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   

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

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

   

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

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

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

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

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

Как писать

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

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

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

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

  

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

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

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

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

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

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

  

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

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

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

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

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

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

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

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

  

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

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

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

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

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

  Вот еще хороший доклад на тему "Как писать полезные технические тексты".

Как итог

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

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

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

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

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

Итак, давайте посмотрим, какая бывает документация:

1. ТЗ требования

   • Виды требований

   • Размер требований

2. Пользовательская документация

3. Примеры

4. Письма от системы

5. Сообщения об ошибках

   • Как искать сообщения

   • Каким должно быть сообщение об ошибке

   • Примеры сообщений об ошибках

6. Поп-ап сообщения

7. Предупреждения что вводить

8. Инструкция по установке

9. Описание полей

10. Маркетинговые материалы

11. Обучение FAQ, презентации

12. Поздравляшки

13. Кнопки

14. Остальное

15. Итого

1. ТЗ требования

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

Виды требований

В каком виде могут быть требования? Есть разные варианты:

Техническое задание

Сухое описание того, как система должна работать. Что уметь делать и как реагировать на ошибки.

Вариант использования

Описание через взаимодействия пользователя с системой:

Пользователь делает то

Система в ответ делает се

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

Пользовательский сценарий

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

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

Картинка

Да да, именно картинка! Вид ее может быть любой:

• Блок-схема

• Диаграмма состояний и переходов

• Скриншот, раскрашенный красным тут должно быть вот так, а тут эдак

• Схема движения транзакций

• ...

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

Что-то другое

Я уверена, что могут быть и другие варианты. Но так как это статья от тестировщика тестировщику, ограничимся базовыми вариантами. За остальным к аналитику =)

У меня на одном из проектов, например, ТЗ было в виде презентации PowerPoint. Вот как генеральный продавал проект спонсорам, так мы и должны были сделать. Картинки + немного текста вот и всё ТЗ. Что непонятно, уточняйте устно.

Размер требований

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

Подробное описание

Обычно встречается на гос проектах. Ооооо, сколько там ТЗ!

Я участвовала на одном таком проекте, где описание функционала, который описывается одной строчкой (есть авторизация через email) занимало 10 листов А4 пошаговое описание интерфейса с картинкой через строку.

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

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

Плюсы:

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

• Если это ТЗ для интеграции у Заказчика будет возникать меньше вопросов А что будет, если...?. Ведь всё уже прописано в ТЗ.

Минусы:

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

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

Краткое описание

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

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

Плюсы:

• Легко поддерживать актуальность.

• При грамотном описании все понятно, без воды.

Минусы:

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

• Если отдать ТЗ третьим лицам (например, заказчику или его тестировщикам), получите много вопросов А что будет, если...?, и придется дополнять требования.

Однако минусы не так уж страшны. Так что если есть возможность пишите кратко!

Нечто среднее

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

Требований нет!

Бывает и такое. Приходите на проект, на, держи, тестируй. А где документация? А нету ее, так проверяй. Что делать?

На самом деле не бывает такого, что требований нет. Они всегда есть. Просто иногда в голове. Заказчика, аналитика, архитектора...

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

• Найти носителя информации.

• Выяснить все подробности.

• Кратенько записать.

• Попросить его проверить.

Тут вы можете сказать:

Эй, але! Я тестировщик! Поставлю задачу аналитику и пусть он делает.

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

Хотите изменить мир? Начните с себя. Заставить других так не работает. Если вам плохо без отсутствия документации, сделайте ее сами. В следующей главе я расскажу, как это можно сделать. Если же вас не парит отсутствие документов живите как живёте.

2. Пользовательская документация

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

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

У нас, например, в вики-системе есть разделы по проекту:

• Внутренний пользователи его не видят. Там все потроха, а еще описание реализации и тестов.

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

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

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

• Требования требования для реализации.

• Пользовательская документация информация о работе системы.

Ограничивается ли документация этими пунктами? Разумеется, нет! Поэтому я и написала эту статью, чтобы вы не забыли про остальные пункты ))

3. Примеры

Всегда проверяйте примеры. Просто ВСЕГДА!

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

Другой вопрос а что относится к примерам? Что проверять то нужно? Давайте разбираться!

Файл-образец

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

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

2. Возьмете пример из системы.

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

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

• Скачивается (вдруг ссылка побилась??)

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

Предзаполненные поля в форме ввода

Что, если у нас просто форма ввода? И туда можно добавить пример! Вот как в Дадате сделано:

Все поля заполнены по умолчанию. Можно просто ткнуть на кнопку Проверить и посмотреть результат. А потом уже обрабатывать свои данные. И поверьте, большинство просто ткнет в кнопку для начала, просто потому, что так проще.

Примеры вызова API-методов

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

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

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

Именно поэтому примеры очень важны. С них начинают работу с системой.

Другие примеры

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

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

Итого по примерам

Примеры очень важны. С них начинают работу с системой.

• Если у вас их нет просите добавить.

• Если они есть тестируйте их!

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

Но и в простом интерфейсе есть место для примеров. Можно облегчить пользователям жизнь, подготовив файл-образец или предзаполнив форму ввода. И они обязательно этими примерами воспользуются. Поэтому примеры мы ОБЯЗАТЕЛЬНО тестируем. Всегда. Это лицо нашего приложения, оно должно работать.

4. Письма от системы

О, это тоже очень важный пункт! Сейчас многие системы присылают приветствия, напоминания, уведомления... Так вот эти письма это тоже документация, причем очень важная ее часть!

Типичные проблемы писем плейсхолдеры, которые:

• не разименовались;

• разименовались, но неправильно.

Что такое плейсхолдер? Это заглушка, которая меняется на нужное значение при отправке письма. Разработчик же не знает заранее, как вас зовут. Но допустим, что он хочет сделать именное письмо:

Привет, Ольга! Спасибо за регистрацию на нашем сайте...

Привет, Андрей! Спасибо за регистрацию на нашем сайте...

Привет, Сладкий пупсик! Спасибо за регистрацию на нашем сайте...

Разработчик пишет письмо, оставляя плейсхолдер вместо имени:

Привет, $username! Спасибо за регистрацию на нашем сайте...

И говорит в коде: Вместо $username подставь имя, которое пользователь ввел при регистрации. Возьми значение из такого-то поля. Теперь, когда Маша-Ваня-Петя регистрируются на сайте, они получают личное письмо со своим именем!

Обычно такие подмены делают на имена и даты. Например, дата, на которую куплен билет. Главное подставить нужное значение! А с эти бывает беда...

В апреле 2017 года я летела в Екатеринбург, на конференцию DUMP[1]. Купила билеты в S7 Airlines заранее в феврале. Перепроверила даты, вроде все правильно, вылетаю 13.04.

Упорный бот пытался впарить мне отель через их сайт и отказ не принял. А 02.02.2017 он прислал мне напоминалку, что у меня скоро полет... И поставил дату... Сегодня о_О

Эй, але, я покупала билеты на апрель! Холодный мороз по коже а вдруг я ошиблась? Нашла письмо с билетами, нет, все хорошо:

Вот же, 13.04!

Значит, просто накосячили в письме. Благо понятно как, раз дата сегодняшняя то вместо моего реального времени полета вставили SYSDATE. Или там и должно быть sysdate, но письмо должно было быть отправлено в апреле...

Проблемы бывают самые разные:

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

Иногда тебе пишут Привет, username!. Забыли подставить значение =))

Иногда неправильно склоняют имя

Иногда неправильно определяют пол

...

То есть в первую очередь мы проверяем в письмах все переменные и плейсхолдеры правильно ли они подставились? Если это строка с именем, проверяем такие моменты:

• А если я пустым оставлю поле?

• А если на другом языке напишу?

• А если спецсимволы введу?

• А если очень длинное имя?

Аналогично с датой:

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

• Правильная ли дата будет в письме?

Ну и, конечно, надо хотя бы разок вычитать все письма на орфографические ошибки!

5. Сообщения об ошибках

Да да, это тоже документация! Поэтому их надо все найти и проверить. Зачем? Давайте я расскажу вам про Pretty roses (взят из интернета, исходного автора давно утеряли):

PASSWORD EXPIRED

"Sorry, your password has been in use for 30 days and has expired You must register a new one."

roses

"Sorry, too few characters."

pretty roses

"Sorry, you must use at least one numerical character."

1 pretty rose

"Sorry, you cannot use blank spaces."

1prettyrose

"Sorry, you must use at least 10 different characters."

1fuckingprettyrose

"Sorry, you must use at least one upper case character."

1FUCKINGprettyrose

"Sorry, you cannot use more than one upper case character consecutively."

1FuckingPrettyRose

"Sorry, you must use no fewer than 20 total characters."

1FuckingPrettyRoseShovedUpYourAssIfYouDon'tGiveMeAccessRightFuckingNow!

"Sorry, you cannot use punctuation."

1FuckingPrettyRoseShovedUpYourAssIfYouDontGiveMeAccessRightFuckingNow

"Sorry, that password is already in use. "

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

Именно поэтому так важно обрабатывать негативные сценарии. Вообще, в идеале нужно делать так, чтобы пользователь просто не мог ошибиться! Например, если в поле можно вводить только целые цифры (количество товара в корзине), что будет лучше?

1. При вводе символа ругаться Ты что, дурак? Тут только цифры!

2. При вводе символа ругаться В поле можно вводить только цифры

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

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

Ведь не дать ввести символы это ограничение, установленное на клиенте. При знании нужных инструментов его легко обойти (начните с Web developer toolbar, вкладка Forms). Поэтому нужно оставить защиту на сервере если пользователь символы таки ввел, выведем ошибку.

См также:

Клиент-серверная архитектура в картинках подробнее о клиенте и сервере

Общая мысль:

Если негативный сценарий можно избежать, сделайте это.

Если избежать его нельзя, тогда уже делайте сообщение об ошибке.

Ну а подробнее про то, как будет лучше пользователю, смотрите в литературе по usability. Вот мой список книг, см раздел Usability-тестирование.

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

В систему можно загружать файл? Тогда пробуем грузить пустой файл, неправильного формата, расширения, разрешения...

В форме редактирования есть обязательные поля? Пробуем их не заполнять или заполнять неправильно...

Система передает ответы через SOAP/JSON? А если отправить неправильный запрос, пустой, с неполными или некорректными данными?

И так далее, и тому подобное.

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

Каким должно быть сообщение об ошибке

Каким должно быть сообщение об ошибке?

Коротким, иначе пользователь заснет, читая его.

Понятным, иначе как понять, что я сделала не так?

Из сообщения должно быть понятно:

В чем моя ошибка?

Что мне сделать, чтобы исправить ее?

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

Извините, что-то сломалось.

Error 38759245, see line 333 in code

Неправильно введены данные.

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

А еще можно сделать сообщение интересным и смешным! Как? Вот, посмотрите, какая прелесть:

Примеры сообщений об ошибках

Dadata

В Дадату можно загружать файлы формата Excel или CSV. Система заранее предупреждает о том, какой должен быть файл:

Если попробовать грузануть туда JPEG, система понятно объясняет, что надо сделать:

Это пример как хорошо, а дальше разберем, как плохо =)

Wildberries, галерея стиля, загрузка фото

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

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

Вроде никаких ограничений нет...

Итак, возрадовались возможности создать образ, грузим фоточку.

Ага, вот и первое ограничение! Файлы должны быть размером поменьше...

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

И что бы вы думали, мне говорят?

Что значит поддерживается только jpg? А я что гружу?

Я гружу JPEG, а мне говорят, что формат неверный, грузи JPEG? о_О

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

Ох ох ох, у меня так было на первых попытках загрузки фоток, пошли старым дедовским методом вставить картинку в Paint, уменьшить масштаб и сохранить как jpg. И вуаля, блин! Загрузилось!

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

Знаете, в чем оказалась проблема? В регистрозависимости расширения файла:

• jpg грузится;

• JPG нет.

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

Как это исправлять? Можно, конечно, разжевать пользователю, что jpg могу, JPG не могу, но... Зачем? Лучше сделать функцию проверки формата регистронезаивисимой. Помните о том, что лучше предотвратить ошибку, чем красиво ее расписать?

Далее, если загрузить слишком маленькую картинку, то получим ошибку:

Файл должен быть не менее 500 пикселей в ширину и 700 в высоту.

Откуда пользователю узнать про этом ограничение? Нужно предупредить! Можно завести такое улучшение:

**********************************************************************

Подсказывать правильный формат и размер файлов для загрузки в ГС

Указать ограничения еще до того, как пользователь начнет грузить файлы. В раздел Мои образы https://lk.wildberries.ru/mylooks добавить надпись:

Принимаются фото:

jpg, jpeg, gif, png, bmp до 2Мб

не менее 500 пикселей в ширину и 700 в высоту

**********************************************************************

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

Какие пиксели? Что надо делать, чтобы сделать их больше или меньше?

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

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

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

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

Wildberries, форум, загрузка фото

Попробовала добавить аватарку на форуме. Иду в Мой кабинет на форуме, далее Изменить фотографию, выбираю фото и...

БЛИН, ДА В ЧТО, ИЗДЕВАЕТЕСЬ, ЧТОЛИ?!!!

Вот что я должна понять из этого сообщения? Почему неудачно? Я что-то сделала не так? Система сломалась? Совсем или мне попробовать через 5 минут?

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

Wildberries, галерея стиля, комментарии

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

Почему черт знает? Потому что текст сообщения непонятный:

Поле содержит ссылку или некорректное выражение

Вроде все ясно, да? Ну нефиг ссылки лепить, всего и делов... Но под огонь попадают нормальные слова или фразы. Например, слово ребенок:

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

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

В общем, когда пишете сообщение об ошибке, думайте о пользователе. Что я из него пойму? Смогу ли исправить ошибку? Пойму вообще, что я сделала не так? Если да то всё круто! Если нет сделайте так, чтобы поняла.

6. Поп-ап сообщения

Pop-up это всплывающее окошко, как навязчивое а вы уже лайкнули нас в фейсбуке?.

В веб приложениях это обычно:

• уведомление о регистрации;

• акционное предложение;

• мини-версия корзины с покупками;

• ...

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

В мобильных игрушках:

• реклама новой игрушки;

• временная акция;

• поздравляшка с успешным окончанием уровня;

• не-поздравляшка ты провалил уровень;

• ...

Что тут стоит проверить? Влезает ли текст в отведенное ему место =))

Пример бага в веб-приложении мы находили в рамках The FedEx Tour: если ввести слишком длинный емейл при регистрации, получим такую картину:

А вот и пример поп-апа в игрушке из серии три в ряд. Если не успел освободить ежа за N ходов, выпадает такое сообщение:

Это на mini ipad было дело. Так что учтите, не только акции во всплывашках! И тестировать такое надо на самых мелких экранах, а потом на средних. А то, может, для телефонов изображение уменьшили, а для айпадов оставили одно, что для макси, что для мини, большой же экран, влезет!

Или вот ещё пример из той же игрушки. Прочтете текст снизу: когда закончится акция?))

7. Предупреждения что вводить

Это когда около поля заранее пишут требования к нему:

Логин должен содержать латинские символы и цифры.

Пароль должен быть длиннее 8 символов и содержать как символы, так и цифры.

...

Чтобы не допустить сообщение об ошибке, предупреждаем о правилах заранее! А требования те же самые, что и у сообщений об ошибках, предупреждения должны быть:

понятные;

в мире пользователя;

выполнимые.

Не надо писать на языке разработки. Пишите для людей, они оценят это больше, нежели формальный стиль общения.

Про выполнимость расскажу такую историю:

Изменение пароля, банк

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

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

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

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

Я же подбирала пароль наугад, а что делать...

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

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

8. Инструкция по установке

Пользовательское приложение

Если это простое или общедоступное ПО его будут устанавливать сами пользователи.

В идеале, конечно, инструкции нет, вместо нее просто .exe файл (если речь про Windows). Помните, как последний раз что-то устанавливали? Скачал, запустил, 10 раз кликнул далее-далее-далее, профит!

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

Но что, если недостаточно просто запустить установочный файлик? Что, если нужно прописать какую-то переменную в Path, например? Тогда комбинируем файл быстрой установки + краткая инструкция.

Например, установка maven. Скачиваем, читаем инструкцию по установке. Она мега-простая, но она есть. Для винды:

1. Check environment variable value e.g.

echo %JAVA_HOME%

C:\Program Files\Java\jdk1.7.0_51

2. Adding to PATH: Add the unpacked distributions bin directory to your user PATH environment variable by opening up the system properties (WinKey + Pause), selecting the Advanced tab, and the Environment Variables button, then adding or selecting the PATH variable in the user variables with the value C:\Program Files\apache-maven-3.6.0\bin. The same dialog can be used to set JAVA_HOME to the location of your JDK, e.g. C:\Program Files\Java\jdk1.7.0_51

3. Open a new command prompt (Winkey + R then type cmd) and run mvn -v to verify the installation.

Переведем:

1. Проверьте текущую переменную окружения, есть ли у вас Java на компьютере?

echo %JAVA_HOME% команда проверки

C:\Program Files\Java\jdk1.7.0_51 результат команды, он говорит, что Java установлена, так как существует переменная %JAVA_HOME%

2. Добавьте maven в PATH: добавьте ссылку на директорию bin в пользовательскую переменную PATH. Для этого откройте системные настройки (WinKey + Pause), выберите вкладку Advanced, нажмите кнопку Environment Variables и добавьте переменную PATH, или выберите ее, если она уже существует. Добавить туда надо значение пути до директории bin, например: C:\Program Files\apache-maven-3.6.0\bin. Аналогично можно и JAVA_HOME добавить, прописав путь до JDK, например C:\Program Files\Java\jdk1.7.0_51

3. Откройте НОВУЮ командную строку (Winkey + R, а потом написать cmd) и выполните команду mvn -v, чтобы проверить установку.

Фактически для установки нужно выполнить ОДНО действие добавить ссылку на директорию bin в PATH. Еще два пункта для проверки того, что все установилось. Maven обращается к JAVA_HOME, поэтому такая переменная должна существовать, что мы и проверяем. И саму установку maven тоже проверяем командой mvn -v.

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

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

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

В этом случае нужно обеспечить полноценную инструкцию по установке, считая, что:

1. Сервер создан с нуля, там НИЧЕГО нет.

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

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

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

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

В идеале, конечно, ставим на голом сервере докер и не паримся с операционными системами и настройками. Выдали готовый докер-файл, готово!

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

Тогда инструкция будет сильно больше! Что может в нее входить:

Подготовка к развертыванию

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

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

• Требования к настройке программно-аппаратной платформы об этом чуть ниже

Требования к настройке какие программы установить, какие права доступа выдать. Соберите всю информацию в одном месте:

• Настройка рабочей станция для ваших сотрудников

• Настройка сервера приложений для ОС *nix

• Настройка сервера приложений для ОС Windows

• Настройка сервера СУБД Oracle

• Настройка сервера СУБД MariaDB

• Настройка Active Directory

• ...

Видите? Windows отдельно, Linux отдельно. Если умеете работать с разными базами данных напишите под каждую отдельную статью.

Инсталляционный пакет

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

Установка системного и специального ПО

Например, продукт написан на Java, а сервер приложения Wildfly. Тогда здесь будут примерно такие разделы:

• Установка параметров ОС Windows

• Создание пользователей ОС Linux

• Установка параметров ОС Linux

• Установка Java

• Установка Wildfly

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

Установка системы

Инструкция по установке системы.

Запуск системы

Короткая инструкция, в которой прописаны команды для запуска и остановки системы.

Что-то ещё

Может быть ещё целая куча документации:

о том, как настраивать систему ПОСЛЕ установки;

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

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

9. Описание полей

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

Вот, например, регистрация в Дадате:

Зачем указывать имя? Чтобы к вам обращались в письмах по нему.

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

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

10. Маркетинговые материалы

Рассылки, которые вы шлете пользователям.

Статьи на Хабре или другом ресурсе.

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

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

• Вычитываем текст, чтобы не было ошибок.

• Если это поп-ап окно, проверяем, что его можно закрыть.

• Если это всплывашка в мобилке, проверяем, не вылезает ли она за экран на небольшом смартфоне.

11. Обучение FAQ, презентации

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

Tutorial

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

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

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

FAQ

Одна или несколько статей, где собраны ответы на типовые вопросы.

F1

Документация из серии Помощь.

Online help

Если у вас есть робот-помощник с зашитыми в него скриптами это тоже документация!

Обучающие статьи

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

Если статья открытая, то туда может вести ссылка прямо с сайта.

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

Видео

Если у вас есть видео в помощь их тоже надо тестировать на устаревание!

Это может быть полноценное видео или кликабельные слайды, такие можно сделать в Wink.

Презентация

Это может быть:

продающая презентация что умеет наш продукт;

обучающая презентация как им пользоваться.

И этотоже документация, которую надо тестировать:

• Выдержан ли стиль компании в презентации?

• Актуальны ли картинки? Не менялся ли интерфейс?

• Насколько полно раскрыта тема? Может, стоит что-то добавить?

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

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

12. Поздравляшки

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

Так вот, когда вы заканчиваете уровень или всю игру, вылезает поздравляшка. Обычно этот всплывающее окно с текстом Поздравляем!. Еще чаще текст будет английским Congratulations!.

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

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

13. Кнопки

Текст на кнопках тоже документация! Вроде очевидно, но все же. Я, например, сталкивалась и с таким:

Как можно пропустить такой баг? Ведь регистрация в интернет-магазине основной кейс, потому что без нее пользователь не может продолжить покупки. Значит, ее тестируют. Видимо, у всех так замылился глаз уже, что подписи на кнопках просто не читают... А вы читайте! =)

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

14. Остальное

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

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

Пользовательское соглашение / оферта а это то, что заменяет нам договор или гарантийный талон в современном ИТ-мире. Пользуясь онлайн-сервисом, вы автоматически соглашаетесь с офертой, которая есть у него на сайте, даже если вы ее не читали ))

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

А то вдруг у вас слишком завышенные требования к железу и никто не купит диск?

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

Итого

Видов документации очень много! Она не ограничивается только лишь требованиями )) Не забывайте про остальную документацию на проекте. И обращайтесь к этому чек-листу за поиском вдохновения что я ещё забыл проверить =)

Самые важные виды документации:

• ТЗ требования

• Пользовательская документация

• Примеры

• Сообщения об ошибках

Чуть менее, но все еще важно:

• Предупреждения о том, как заполнять поле

• Описание поля (зачем мне его заполнять?)

• Предзаполненный текст в поле ввода

• Инструкция по установке

• Маркетинговые материалы

• Статьи на Хабре или где-то еще

• Обучение материалы

• FAQ

• Online help

• Презентации

А еще есть:

• Пользовательское соглашение / оферта

• Гарантия

• Упаковочный текст и графика

Это тоже нужно проверять, но уже не в приоритете!

PS больше полезных статей ищите в моем блоге по метке полезное. А полезные видео на моем youtube-канале

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

Вот только на что обращать внимание при тестировании? Есть набор основных характеристик, которыми должна обладать хорошая документация:

1. Полнота

2. Однозначность

3. Непротиворечивость

4. Необходимость

5. Осуществимость

6. Тестируемость

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

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

1. Полнота

Все ли описано? Ничего не забыли? Вдруг у нас остался неописанный функционал или параметр API-метода?

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

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

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

А что, если... ?

У Заказчика уточнили, документацию пополнили! В остальном меня всё устроило, вроде нормально описано, всё учтено.

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

А как только стала расписывать план автотестов, сразу увидела белые пятна. При этом у меня 10 лет опыта в тестировании. Не полагайтесь на память и быстренько мысленно прикину, выделите полчаса и распишите чек-лист проверок подробно.

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

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

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

2. Однозначность

Требования должны трактоваться всеми одинаково.

Отчет должен загружаться быстро что значит быстро?

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

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

Налицо конфликт интересов. И ведь каждый будет тыкать в ТЗ для отстаивания своей позиции. Лучше конкретизировать:

• Отчет за год должен загружаться не более секунды.

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

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

• Аналитик будет думать, что там будет значение 0. Деньги же, цифра!

• Разработчик сделает пустое поле, не указано ведь ничего! А это что-то сломает...

Если в требованиях не указано, как обработать ошибочный сценарий, разработчик может:

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

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

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

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

Если этот документ отправят заказчику, надо расписать вообще всё потому что у заказчика свои тестировщики, и они обязательно зададут кучу а что, если...?. Если они хорошие тестировщики, разумеется. Это вы знаете свою программу и представляете, как она реагирует на ошибки или что-то такое. Тестировщик заказчика этого не знает, он будет уточнять.

3. Непротиворечивость

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

Например, есть страница нефункциональных требований, где написано, что любая страница должна грузится не более 3 секунд. Аналитик пишет ТЗ на новый модуль отчетности, который использует много данных и сложные формулы. И он пишет, что отчет может грузиться вплоть до минуты. Явное противоречие!

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

4. Необходимость

Помните главный принцип: Кратко, но емко? Он действует и в документации тоже.

Круто, когда документация полная. Но это не значит, что простой функционал надо растечь на 10 листов А4. Когда документации много, сложно проверить полноту, сложно удержать в голове, о чем уже говорил, не повторяться и не противоречить самому себе.

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

Пишите только то, что необходимо:

• В ТЗ функционал, основной сценарий и альтернативы, типы ошибок.

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

5. Осуществимость

А можно ли реализовать то, что тут написано? Насколько это будет сложно и дорого?

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

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

Но вот беда нельзя поискать по двум параметрам ОДНОГО атрибута. Если сказать Найди мне домашний адрес с улицей Ленина, система вернет:

1. Васю: домашний адрес с улицей Ленина.

2. Петю: домашний адрес с переулком Турчанинов и рабочий с улицей Ленина.

Почему так?

Это баг в системе? Или просто нельзя сделать такой поиск, это неосуществимо? Нужно смотреть по коду.

В той системе для поиска использовали Lucene. Его можно настроить по-разному:

o поиск по любому полю;

o поиск по конкретному полю;

o множественный поиск по конкретному атрибуту (в одном адресе проверить и тип, и улицу);

o ...

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

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

Осуществимо желание отсеять Петю? Да. Но это просто не нужно. Потому что вреда принесет больше, чем пользы. Ради того, чтобы в выборку из 1000 человек не попали 10 лишних, платить несколько миллионов за дополнительные мощности серверов смысла просто нет.

6. Тестируемость

Можно ли протестировать этот функционал?

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

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

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

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

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

А как мне указать вторую очередь? Или папка jms это то, что в обе уйдет?

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

Ну и ничего, доделали, написала тестов!

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

При этом бывает и так, что тестировать все равно придется разработчику. Скажем, когда делают рефакторинг, что может проверить тестировщик? Только регресс провести, посмотреть, что ничего не отломалось. А если есть автотесты, то это проверят они =)

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

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

Бонус: мнемоника CIRCUS MATTA и другие доп материалы

CIRCUS MATTA мнемоника для ревью пользовательских историй. Это как раз про тестирование требований! Истории должны обладать качествами:

• Completeness полнота

• Independent независимость

• Realisable реализуемость

• Consistency консистентность

• Unambiguity однозначность

• Specific специфика заказчика

• Measurable измеримая

• Acceptable приемлемая

• Testable тестируемая

• Traceable трассируемая (можно проставить взаимосвязи)

• Achievable достижимая

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

См также:

Тестирование документации к программным продуктам тут целых 18 критериев хорошей документации!

Тестирование требований. Особенности статья от Лаборатории Качества.

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

Когда обычной инструкции не достаточно

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

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

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

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

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

Все начинается с идеи и оценки ее реализации

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

Кто нужен для производства видеоинструкции

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

• Руководитель проекта или продукта. Как вы уже догадались, того продукта, для которого мы будем снимать ролик.

Зачем он нам: сформулировать цель ролика, ответить на вопросы в процессе написания сценария, вычитать сценарий и оценить ролик.

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

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

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

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

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

Маркетолог. Он смотрит финальную версию и загружает ее на YouTube-канал.

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

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

Сколько времени нужно на производство ролика

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

Что нужно из оборудования

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

• Штатив. На него можно закрепить мобильный телефон для съемки живых кадров.

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

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

• Монтажная программа. В ней мы монтируем и собираем видео. У нас их две: для простого линейного монтажа мы используем программу Movavi, а для более сложного Adobe Premiere Pro. Первая очень простая и быстрая в освоении. Конечно необходимо, чтобы все используемое ПО было лицензированным.

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

• Программа для обработки звука. В ней мы обрабатываем звук. Можно установить специальную, а можно использовать возможности программы Adobe Premiere Pro.

• Текстовый редактор. В нем мы пишем сценарий. Использовать можно любой, но лучше всего тот, в котором организована возможность совместной работы с документом. Например, можно использовать Microsoft Word 2016 или Google Docs.

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

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

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

Обязательно ли писать сценарий

Ответ ДА. Сценарий нужен даже, если ваш ролик длится 20 секунд. Ролики без сценариев очень отличаются, в них нет нужных акцентов и логики. А если в таком ролике еще есть закадровый голос, то это вообще веселье. Что делает человек, который записывает закадровый голос: он просто комментирует все, что видит, а так быть не должно. Здесь мы можем услышать неоправданные паузы, слова-паразиты и т.п.

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

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

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

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

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

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

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

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

Совет 1. Записывайте звук отдельно. Если вы снимаете живые кадры и хотите, чтобы они сопровождались закадровым голосом, то пишите звук отдельно. Качество звука это очень важный параметр.

Мы записываем закадровый голос специальный диктофон или на диктофон мобильного телефона.

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

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

Совет 2. Обрабатывайте звук. Убирайте шумы и выравнивайте звук по громкости.

Совет 3. Думайте про свет. Плохо когда света мало, но также плохо когда его много. Не снимайте против источника света. Он должен быть либо перед объектом съемки, либо сбоку.

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

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

Мы снимали для ролика кадры:

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

• Крупный план: смарт-карта в ладони. Так мы показали, как выглядит смарт-карта.

• Крупный план: смарт-карта, мобильное устройство и руки человека. Так мы показали, как работать со смарт-картой на мобильном устройстве.

После того, как мы отсняли реальные кадры, начинаем снимать видео с экрана.

Как снимать видео с экрана компьютера или мобильного устройства

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

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

Есть моменты, которые можно ускорить. Например, вы показываете как заполняете стандартные поля (фамилия, имя, отчество), такое пользователь сможет сделать сам.

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

Не забывайте про то, что в вашем ролике не должно быть каких-то личных данных (номеров телефонов, IP-адресов, адресов электронных почт и т.п.), их надо замылить.

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

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

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

Теперь у вас есть реальные кадры, есть кадры, снятые с экрана, что делать дальше? Монтировать ролик?

Нужна ли музыка

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

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

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

Музыку выбрали, теперь можно монтировать.

Как монтировать ролик

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

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

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

Редактирование голоса. При редактирование голоса необходимо вырезать: паузы, ошибки, слова-паразиты.

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

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

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

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

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

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

Жизнь ролика на YouTube

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

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

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

Также мы открыты к диалогу, если есть вопросы пишите в комментарии.