Как вы описываете свое решение / систему?

Question

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

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

Теперь, будучи самим программистом, я вижу, что невозможно диктовать и говорить: «каждое решение должно определять X с использованием Y и представлять его в соответствии с Z.», поскольку X Y Z не всегда применимо и т. Д.

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

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

обновление Это было непонятно, но я не имел в виду требования пользователя с X Y Z. Я имел в виду все возможные типы документации, которые может иметь система. Поэтому считайте, что «невозможно утверждать, что каждое решение должно иметь: список необходимых платформ; руководство по эксплуатации для серверного программного обеспечения; требуемые основные данные; матрица требований пользователя против тестов; спецификация интерфейса пользователя. Хотя имеет смысл производить такие ограниченные набор требований, трудно быть четким и точным, поскольку то, что является наиболее важным / актуальным, отличается от проекта к проекту.

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

Answer 1

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

Это также зависит от того, на каком уровне документации вы говорите: Руководство по архитектуре на основе приложения см. В Руководство по архитектуре приложений Microsoft 2.0 (недавно выпущено).

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

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

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

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

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

Answer 2

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

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

Как [X]
Я хочу [Y]
так что [Z]

В том же духе вы можете посмотреть на Варианты использования

Answer 3

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

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

Answer 4

В основном, есть много способов сделать документацию для проектов. 2 подхода, которые я использовал в прошлом: 1) Разработка на основе прецедента и 2) Разработка на основе тестирования. Поскольку я использовал тестовую разработку только один раз, я советую, как использовать разработку на основе сценариев использования.

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

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

2. Спецификация требований к программному обеспечению - здесь аналитик разбивает требования пользователя на функциональные спецификации. Аналитик создает потоки на основе потребностей пользователя. Здесь вы начинаете использовать UML. Начните с диаграмм вариантов использования и действий, чтобы получить представление о том, как система будет чувствовать себя. Получите другие производные спецификации, такие как требования безопасности и другие потребности, такие как ограничения инфраструктуры.

3. Описание разработки программного обеспечения - это технический документ, который разработчик архитектуры или решения создает для разработки решения, отвечающего требованиям. Архитектор разбивает функциональные спецификации и переводит потоки в технические характеристики. Каждый вариант использования может быть разбит на диаграммы последовательности и схемы связи. Что вы можете сделать с этими диаграммами, так это начать создавать функции для классов. Эти диаграммы могут быть использованы для разработки диаграмм классов. State Machines, как вы знаете, ломает диаграммы классов, но я обычно не захожу так далеко. Вы также можете задокументировать всю архитектуру и разбить ее компоненты в этом документе, используя Компонентные Структуры. Документ может также включать инфраструктуру развертывания, в которую будет помещена система.

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

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

Пример матрицы: «Бизнес нужна A» -> «Функциональная спецификация A» и «Функциональная спецификация B» «Функциональная спецификация A» -> «Компонент A», «Компонент B» и «Компонент C» «Компонент B» -> «Класс A» и «Класс B»

Конечно, это всегда выглядит лучше в электронной таблице.

Answer 5

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

Answer 6

Очень мало, к сожалению!

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

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

Answer 7

TOGAF (Open Group Architecture Framework) определяет «метод» того, как архитектор должен определять решение. Часть TOGAF также участвует в определении того, какие входные и выходные данные должны создаваться в рамках архитектурного проекта.

Тем не менее, для вашего вопроса о том, какая документация вам нужна, и которая должна быть поделена между разными людьми (BA, программисты, тестировщики, менеджеры и т. Д.), Вы должны посмотреть на Views и ViewPoints в TOGAF. Все эти люди, которых вы упоминаете, являются вашими заинтересованными сторонами, а Views и ViewPoints решают проблемы заинтересованных сторон. Поэтому я бы посоветовал вам взглянуть на Views и ViewPoints.

Answer 8

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

1. Хранилища данных (Где хранятся данные? Как к ним обращаться?)
2. Формат данных (Какие форматы используются? Введены ли новые? Спецификация) размер расти?
3. Конфигурация (Что можно настроить, что по умолчанию)
4. Зависимости библиотеки / инфраструктуры / пакета (поставщик, лицензия, версия)
5. Построение решения (как получить все файлы и т. Д. И пошаговое построение)
6. Модули (определенная область применения / почему был введен модуль)
7. Документация по классам / исходным кодам (генерируется Doxygen или эквивалентной)

Также представляет интерес: 1. Безопасность (Какая область решения находится под защитой, шифруется и т. Д.) 2. Передача данных (что передается между дисками / сетью? По каким переменным

Answer 9

Возможно, потому что я только что прочитал это, и оно все еще гудит у меня в голове, но я думаю, что стоит прочитать 37signals Getting Real . Хотя речь идет о запуске проекта, подход к документации мне очень нравится (как программисту). Это не всем по вкусу, но если другие придерживаются этого подхода, это может даже сделать документацию приятной. Я нашел это так.