Предисловие: Я новичок в мире документации, так что прошу относиться к моим вопросам соответственно
И так, Всем приветы. Передо мной стоит задача написать документ, описывающий создание конференций. В этом документе я должен разобрать все возможные случаи, с описанием параметров внутри сообщений. И я столкнулся с проблемой нагромождения документа и всевозможных повторов в разных "концах" сценариев. Я читал две книги по написанию Use Case, и в обоих написано не совсем то, что мне нужно. Из чего я сделал вывод, что тот документ, который я хочу написать, скорее всего не совсем "варианты использования".
Я бы хотел что бы мой документ был максимально наглядным, чему могут способствовать Call Flow, и при этом весьма содержательным, т.к. там должны быть описаны параметры. Но я столкнулся с проблемой: например я описываю создание конференции, и, в процессе их создания, всем участникам рассылаются приглашения. И тут возникают три варианта:
1. Все участники не доступны (конференция создается не через клиентскую звонилку, а через веб интерефейс).
2. Кто то один из участников не доступен.
3. Все доступны, конференция успешно создана.
Пока процесс создания конференции дойдет до этого этапа, описан уже большой Call Flow. И я подумал а почему бы не сделать так:
Я описываю call flow, т.е.: "(1)Посылается запрос на создание, бла бла бла...", дохожу до нужного момента и прям в тексте пишу: "(15.2), участник В не доступен", и вставляю маленький call flow с нужными сообщениями и описанием специфических параметров. Но такой вариант написания документа очень громоздкий. В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
Здравствуйте, slava.4e, Вы писали:
S4>В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
Общий подход — использование так называемых alternate/exception flow, как часть описания варианта использования.
Т.е. вasic flow лучше не перегружать особенностями исключительных, специальных ситуаций.
Здравствуйте, bkat, Вы писали:
B>Здравствуйте, slava.4e, Вы писали:
S4>>В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
B>Общий подход — использование так называемых alternate/exception flow, как часть описания варианта использования. B>Т.е. вasic flow лучше не перегружать особенностями исключительных, специальных ситуаций.
Т.е. лучше в начале представить базовый сценарий, с его описанием, а потом нарисовать alternative flow, с указанием альтернативных веток и их описанием? Но подобные диаграммы слишком абстрактны, для подобного рода задач, на мой взгляд. Я только что попытался на бумаге нарисовать, и ничего толкового не вышло. Дело в том что мне нужно расписать почти каждое сообщение, с его специфическими параметрами, без которых услуга работать не будет. А сообщений там порядка 30, конечно если исключить все подтверждения, не несущие в себе важных, с точки зрения создания и конфигурации конференции, параметров, получится около 20 сообщений, которые никак нельзя упускать, как и некоторые их особенности.
Здравствуйте, slava.4e, Вы писали:
S4>Здравствуйте, bkat, Вы писали:
B>>Здравствуйте, slava.4e, Вы писали:
S4>>>В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
B>>Общий подход — использование так называемых alternate/exception flow, как часть описания варианта использования. B>>Т.е. вasic flow лучше не перегружать особенностями исключительных, специальных ситуаций.
S4>Т.е. лучше в начале представить базовый сценарий, с его описанием, а потом нарисовать alternative flow, с указанием альтернативных веток и их описанием?
Именно так.
S4>Но подобные диаграммы слишком абстрактны, для подобного рода задач, на мой взгляд. Я только что попытался на бумаге нарисовать, и ничего толкового не вышло. Дело в том что мне нужно расписать почти каждое сообщение, с его специфическими параметрами, без которых услуга работать не будет. А сообщений там порядка 30, конечно если исключить все подтверждения, не несущие в себе важных, с точки зрения создания и конфигурации конференции, параметров, получится около 20 сообщений, которые никак нельзя упускать, как и некоторые их особенности.
Что значить абстрактны?
Use Case штука очень конкретна и показывает поведение системы с точки зрения пользователя.
О каких параметрах и сообщениях ты говоришь?
Не пытаешься ли ты смешать варианты использования с деталями реализации?
А вообще твоя проблема весьма стандартна.
Найти достаточноый уровень детализации весьма не просто.
Если в компании еще нету сформировавшихся представлений о том, что есть хорошо,
то обычно либо вообще ничего не пишут, либо пишут слишком много и слишком детально.
В итоге выясняется что никому это так детально не нужно
Короче для начала я бы попытался ответить на вопрос кому вообще нужна эта документация
и для каких целей. Предположим что варианты использования
вам нужны чтобы специфицировать систему для девелоперов и тестеров.
У нас в этих случаях варианты использования используются только как иллюстрация формальных спецификакий.
В стандартном случае рисуется GUI Mockup.
По нему создаются описания вариантов использования (обычный текст).
Ну и далее следует набор формальных спецификаций (тоже обычный текст).
В большинстве случаев такого набора достаточно, чтобы понять что должна делать система.
В тривиальных или специальных случаях Mockup'ы или варианты использования опускаются.
В общем я не совсем уверен, в чем у тебя затруднения, но сдается мне,
что ты опускаешься в ненужных детали реализации.
Скорей всего поэтому и получается объемно и необозримо.
Здравствуйте, bkat, Вы писали:
B>Здравствуйте, slava.4e, Вы писали:
S4>>Здравствуйте, bkat, Вы писали:
B>>>Здравствуйте, slava.4e, Вы писали:
S4>>>>В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
B>>>Общий подход — использование так называемых alternate/exception flow, как часть описания варианта использования. B>>>Т.е. вasic flow лучше не перегружать особенностями исключительных, специальных ситуаций.
S4>>Т.е. лучше в начале представить базовый сценарий, с его описанием, а потом нарисовать alternative flow, с указанием альтернативных веток и их описанием?
B>Именно так.
S4>>Но подобные диаграммы слишком абстрактны, для подобного рода задач, на мой взгляд. Я только что попытался на бумаге нарисовать, и ничего толкового не вышло. Дело в том что мне нужно расписать почти каждое сообщение, с его специфическими параметрами, без которых услуга работать не будет. А сообщений там порядка 30, конечно если исключить все подтверждения, не несущие в себе важных, с точки зрения создания и конфигурации конференции, параметров, получится около 20 сообщений, которые никак нельзя упускать, как и некоторые их особенности.
B>Что значить абстрактны? B>Use Case штука очень конкретна и показывает поведение системы с точки зрения пользователя. B>О каких параметрах и сообщениях ты говоришь? B>Не пытаешься ли ты смешать варианты использования с деталями реализации?
Как я говорил выше, я почти впервые с этим столкнулся. И, как любой, новоиспеченный, выпускник ВУЗа, я имею весьма расплывчатые представления о документации. Так что, я был бы рад, если бы ты показал где можно почитать про виды, формы и предназначение документов, необходимых для девелоперовских и инженерных задач. Если, конечно, они где нибудь сведены в один документ/статью.
В общем я не очень представляю что такое детали реализации .
Я говорю о параметрах, что передаются, например, в SIP, при создании конференций. Таких, как: Conf URI, какие то параметры в XML, в сообщениях NOTIFY, и прочие идентификаторы, параметры и значения заголовков.
Про то что Use Case это штука с точки зрения пользователя, я понял когда прочитал две книги, описывающие принципы его написания. Но мне надо что то в этом духе, только на уровне протоколов, в моем случае это HTTP и SIP.
B>А вообще твоя проблема весьма стандартна. B>Найти достаточноый уровень детализации весьма не просто. B>Если в компании еще нету сформировавшихся представлений о том, что есть хорошо, B>то обычно либо вообще ничего не пишут, либо пишут слишком много и слишком детально. B>В итоге выясняется что никому это так детально не нужно
B>Короче для начала я бы попытался ответить на вопрос кому вообще нужна эта документация B>и для каких целей. Предположим что варианты использования B>вам нужны чтобы специфицировать систему для девелоперов и тестеров. B>У нас в этих случаях варианты использования используются только как иллюстрация формальных спецификакий. B>В стандартном случае рисуется GUI Mockup. B>По нему создаются описания вариантов использования (обычный текст). B>Ну и далее следует набор формальных спецификаций (тоже обычный текст). B>В большинстве случаев такого набора достаточно, чтобы понять что должна делать система. B>В тривиальных или специальных случаях Mockup'ы или варианты использования опускаются.
Когда я вплотную занялся этим вопросом, читал различные форумы и статьи, я понял что нет какого то общего понимания, у большинства, и что это является огромной проблемой при разработке. Так что, как минимум, теперь, она нужна лично мне, что бы получить опыт, представление и понимание. Этакий вклад в борьбу с безграмотностью
Нам нужно следующее: документ, который описывает все возможные ситуации, на уровне протоколов сигнализации. Что бы потом, по этим Use Case, написать логику для Application Server и тестовые спецификации. Т.е. документ должен описывать сценарии, сообщения, и указать на важные параметры, на которых "завязана" логика.
B>В общем я не совсем уверен, в чем у тебя затруднения, но сдается мне, B>что ты опускаешься в ненужных детали реализации. B>Скорей всего поэтому и получается объемно и необозримо.
Ну, по большей части, затруднения в отсутствии опыта в написании документации
Кстати, большое спасибо за отзывчивость!
И так, я решил, приняв во внимание советы, попробовать написать этот документ с начала. И вот как я это делал:
Я нарисовал Call Flow, и все ключевые моменты, в которых может произойти ответвления от базового сценария, обозначил A1, B1, C1 и т.д. После чего я нарисовал Alternative Flow, где указал точки в альтернативных ветках (B2, B3, C2 и т.д.), на сколько правильно решение сделать так?
И еще, у меня теперь появилась новая головная боль: структура текста.
Как это все свести в логически цельную структуру? Сделать что то вроде:
1. Basic call flow
2. Alternate and exception flow
3. A1 point
(1) Scheduled server sends request with SIP URI initiator and SIP URI participants, which are marked as "owner" and "participant", to Application Server (AS), for creating Conference.
(2) 204 confirmation regarding start of query processing is being sent.
4.B1 point
(3) Aplication Server sends query to creating cinference to media server, which contains Conference ID.
.
.
.
и т.д.?
2й пункт будет содержать дерево, состоящее только из точек, что обозначены в первом пункте, + точки для alternative и expetion веток.
Т.е. очевидно тут проблема в описании Call Flow, и всей логики. Хотя я подозреваю это можно превратить в красивую структуру. Но, к сожалению, не могу придумать как. Тем более что в точках из альтернативных веток, будет находиться новое call flow, но только для определенного участка.
Спасибо! Но, я читал эту книгу. Правда, не знал что она переведена на русский. Но в этом то и проблема, что у меня не тривиальный случай: у меня есть call flow, в котором описан весь процесс создания конференции, в котором принимают участие 4 сервера, и два абонентских терминала. И мне нужно описать сообщения, с их параметрами, и все случаи, например, когда один из абонентов не зарегистрирован, либо один из абонентов занят и т.д. И я как раз мучаюсь с тем как это описать потому, что стандартные шаблоны не очень подходят. В call flow все сообщения пронумерованы, что бы было их удобнее описывать. Как это будет выглядеть если я буду описать по этой книге:
опущу стандартные пункты
...
...
1.4 Basic flow
Тут я представляю схему, с выделенным, цветом, основным сценарием, и ответвления от него.
1.5 Основной сценарий
Тут я кратко описываю все элементы из схемы.
1.6 Main call flow
Тут я представляю call flow основного сценария.
1.7 Расширения
Тут я представляю описания каждого сообщения из call flow
и тут я натыкаюсь на проблему: в расширенном, по идее, мне надо описать еще и alternative и expetion ветки в логике. Но для этого необходимо представить call flow и для них. Так вот как и куда его лучше впихнуть?
S4>и тут я натыкаюсь на проблему: в расширенном, по идее, мне надо описать еще и alternative и expetion ветки в логике. Но для этого необходимо представить call flow и для них. Так вот как и куда его лучше впихнуть?
К сожалению, я не знаю задачи, поэтому посоветовать конкретно не могу. Если основные вопросы как и куда, то сначала можно впихнут куда-нибудь, потом в процессе правки, все встанет на свои места. Например, сначала привести все call flow, потом дать описание.
Здравствуйте, slava.4e, Вы писали:
S4>Но, к сожалению, не могу придумать как.
Мне кажется проблема в том, что вы пытаетесь весь запихнуть весь документ в одну картинку. Не нужно зацикливаться на диаграммах, тем более на call flow. Возьмите чистый лист и начните описывать идеальнй сценарий простым текстом. Пишите только самое главное не отвлекаясь на мелочи. Никакой обработки ошибок, никаких исключительных ситуаций, все это потом. Сейчас вы пишете основной сценарий. Он отвечает на вопрос: "Как эта фича работает?" После того как основной сценарий готов, начинайте описывать уточнения. Они отвечают на вопросы: "Что будет если случится Х?". И уже после того как все детали описаны текстом, можно рисовать диаграммы если у вас сохранилось такое желание. Назначение диаграмм дополнять, а не заменять текст.
Если вы хотите чтобы ваш документ был полезным, выделите нормативную часть (что должно быть реализовано) и мотивацию (почему это должно быть реализовано именно так). Посмотрите RFC или на спецификации WHATWG. Это хороший пример "как правильно".
Здравствуйте, Miroff, Вы писали:
M>Здравствуйте, slava.4e, Вы писали:
S4>>Но, к сожалению, не могу придумать как.
M>Мне кажется проблема в том, что вы пытаетесь весь запихнуть весь документ в одну картинку. Не нужно зацикливаться на диаграммах, тем более на call flow. Возьмите чистый лист и начните описывать идеальнй сценарий простым текстом. Пишите только самое главное не отвлекаясь на мелочи. Никакой обработки ошибок, никаких исключительных ситуаций, все это потом. Сейчас вы пишете основной сценарий. Он отвечает на вопрос: "Как эта фича работает?" После того как основной сценарий готов, начинайте описывать уточнения. Они отвечают на вопросы: "Что будет если случится Х?". И уже после того как все детали описаны текстом, можно рисовать диаграммы если у вас сохранилось такое желание. Назначение диаграмм дополнять, а не заменять текст.
M>Если вы хотите чтобы ваш документ был полезным, выделите нормативную часть (что должно быть реализовано) и мотивацию (почему это должно быть реализовано именно так). Посмотрите RFC или на спецификации WHATWG. Это хороший пример "как правильно".
Нет, я совершенно этого не хочу. В документе будет две конференции, каждая конференция разбита на три этапа: создание, приглашение новых участников, завершение. Я пишу о том, что я начал описывать создание одной конференции. Но при ее создании может возникнуть множество различных ситуаций, что я и хочу учесть. В RFC описан один протокол, а я описываю платформу, на которой, для реализации данной услуги, будут использоваться два протокола. Но это не суть. Суть в том, что я хочу свести все ситуации в один документ. Я хочу что бы в этом документе были все call flow, т.к. это больше всего подходит для описания протоколов, в тех же RFC и используется этот метод. Но мне нужен и текст, описывающий что же происходит в этих call flow. Так вот, еще раз повторяюсь, какая проблема: при отклонении от базового сценария, мне нужно рисовать новые call flow. Но как тогда форматировать текст? Мб мне нужно сделать какое то особое обозначение сообщений, а не просто пронумеровать их, и как вставлять описание новых веток? Вставить все call flow сразу, включая маленькие call flow, на которых будет показан только участок отличающийся от основного, или есть другие способы предоставления этой информации?
Здравствуйте, slava.4e, Вы писали:
S4>Я описываю call flow, т.е.: "(1)Посылается запрос на создание, бла бла бла...", дохожу до нужного момента и прям в тексте пишу: "(15.2), участник В не доступен", и вставляю маленький call flow с нужными сообщениями и описанием специфических параметров. Но такой вариант написания документа очень громоздкий. В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
1. Не описывайте поток работ в терминах сообщений. Начните с самого верха и уточняйте картину. А внизу уже (в подразделах) — сообщения.
2. Может сначала в тексте в общих чертах накидать структуру, а зтем уже рисовать схемки (для наглядности). Часто в тексте получается быстрее.
3. Про RFC уже сказали. Думаю, будет полезно посмотреть на структуру.
Предлагаю такую структуру.
Раздел N. Работа конференции.
Основной поток:
1. Создание
2. Приглашение участников
3. Работа конференции
4. Завершение конференции
...
Раздел N+1. Приглашение участников.
Основной поток (наиболее частый, без ошибок и т.п.):
1. Сервер отправляет сообщение ...
2. Клиент отправляет ответ серверу ...
3. Сервер формирует канал.
Альтернативные потоки: 2а. Какой-нибудь участник не доступен.
Сервер отправляет информацию други участникам о том, кто и почему не доступен с помошью таких-то сообщений. Участник исключается из конференции.
2б. Не доступен не один участник.
Сервер уведомляет об этом ...
2в. Клиент запросил особые параметры
Сервер делает ... или отказывает, посылая сообщение (имя сообщения)
3а. Сервер не смог открыть канал.
Сервер делает ...
Раздел N+2... Описание и форматы сообщений
Сообщение ....
Описание параметров. Когда используется и т.д.
S4>И так, Всем приветы. Передо мной стоит задача написать документ, описывающий создание конференций. В этом документе я должен разобрать все возможные случаи, с описанием параметров внутри сообщений.
Такие документы обычно начинаются с Purpose и Scope, т.е. с назначения документа ("Кто будет читать", "Зачем будет читать", "Что после прочтения документа он получит") и его области применимости (в т.ч. "до какого уровня будет детализировано").
Думаю, участикам ветки было бы проще дать вам разумный совет, если бы вы привели текст purpose & scope. Потому что каждый сейчас смотрит со своей стороны, и думает, "вот если бы я писал документ, я бы написал вот так". Но в реальности вы пишете документ не для абстрактного читателя, а для конкретных людей (вряд ли вы RFC сочиняете, так?) и с конкретной целью. В зависимости от этого можно будет порекомендовать тот или иной способ описания.
А то, может статься, ваш документ будет основным источником информации для составления тест-планов. В этом случае, вероятно, значительно лУчшим подходом может стать набор атомарных user stories.
Здравствуйте, Буравчик, Вы писали:
Б>Здравствуйте, slava.4e, Вы писали:
S4>>Я описываю call flow, т.е.: "(1)Посылается запрос на создание, бла бла бла...", дохожу до нужного момента и прям в тексте пишу: "(15.2), участник В не доступен", и вставляю маленький call flow с нужными сообщениями и описанием специфических параметров. Но такой вариант написания документа очень громоздкий. В общем, буду рад если кто нибудь поделится опытом, как это сделать наиболее красиво, эффективно и при этом не разбивая на тысячу разных документов.
Б>1. Не описывайте поток работ в терминах сообщений. Начните с самого верха и уточняйте картину. А внизу уже (в подразделах) — сообщения. Б>2. Может сначала в тексте в общих чертах накидать структуру, а зтем уже рисовать схемки (для наглядности). Часто в тексте получается быстрее. Б>3. Про RFC уже сказали. Думаю, будет полезно посмотреть на структуру.
Б>Предлагаю такую структуру.
Б>Раздел N. Работа конференции.
Б>Основной поток: Б>1. Создание Б>2. Приглашение участников Б>3. Работа конференции Б>4. Завершение конференции
Б>...
Б>Раздел N+1. Приглашение участников. Б> Б>Основной поток (наиболее частый, без ошибок и т.п.): Б>1. Сервер отправляет сообщение ... Б>2. Клиент отправляет ответ серверу ... Б>3. Сервер формирует канал.
Б>Альтернативные потоки: Б>2а. Какой-нибудь участник не доступен. Б>Сервер отправляет информацию други участникам о том, кто и почему не доступен с помошью таких-то сообщений. Участник исключается из конференции.
Б>2б. Не доступен не один участник. Б>Сервер уведомляет об этом ...
Б>2в. Клиент запросил особые параметры Б>Сервер делает ... или отказывает, посылая сообщение (имя сообщения)
Б>3а. Сервер не смог открыть канал. Б>Сервер делает ...
Б>Раздел N+2... Описание и форматы сообщений Б> Б>Сообщение .... Б>Описание параметров. Когда используется и т.д.
