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

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

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

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

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

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

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

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

Ответы

Ответ 1

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

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

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

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

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

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

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

Ответ 2

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

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

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

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

Ответ 3

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

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

Ответ 4

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

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

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

Ответ 5

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

Ответ 6

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

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

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

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

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

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

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

Пример матрицы: "Business Need A" → "Функциональная спецификация A" и "Функциональная спецификация B" "Функциональный Spec A" → "Компонент A", "Компонент B" и "Компонент C" "Компонент B" → "Класс A" и "Класс B"

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

Ответ 7

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

Ответ 8

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

  • Хранилища данных (Где хранятся данные? Как это делается?)
  • Формат данных (какие форматы используются? Любая новая введенная спецификация) размер растет?
  • Конфигурация (что можно настроить, что по умолчанию)
  • Библиотека/Framework/Зависимости пакетов (поставщик, лицензия, версия)
  • Построить решение (как получить все файлы и т.д. и шаг за шагом строить)
  • Модули (Определенная область действия/почему был введен модуль)
  • Документация класса/исходного кода (сгенерирована Doxygen или эквивалентной)

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

Ответ 9

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

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