• 1 reply
  • Latest Post - ‏2010-06-07T19:40:18Z by SystemAdmin
3 Posts

Pinned topic Which artifact to use for describing how a system is built ?

‏2010-03-18T13:35:21Z |
Hi all :-)

I'm about to write documentation for an already existing system. I.e read source-code and interview developers. The reasons for this are:
  • Detailed documentation for the system does not exist.
  • The documentation shall serve as requirement-input when a new system shall be implemented.

The result shall be possible to read by any stakeholder. Yet it shall describe details on a technical level.
I want to write something like this :
"1. The system receives the file and archives it without analyzing the content. The archiving serves auditing and history purposes.
2. The system detects the file’s message type and determines that the file is an XYZ Interchange file containing one or more AAA / BBB /messages.
3. Next, the system filters the file, removing any Carriage Return (CR) and Line Feed (LF) characters that may have been added during the file transfer. CR LF characters are never part of XYZ messages and must be removed.

It looks like usecase but it's not. A usecase is more WHAT shall happen. Not HOW it is done.

Q1: Which artifact suits best to use for this kind of documentation? (Sequence-diagram perhaps? Diagrams might be tricky to understand for everyone though).
Q2: The system have ~100 unique scenarios that shall be described in this form. Most of them are very similar to each other, but with small differences here and then. How can I write so few "how-usecases" as possible and still fetch all details? Refer to a list of special requirement or similar?

/Best Regards
Joakim Carlsson
Updated on 2010-06-07T19:40:18Z at 2010-06-07T19:40:18Z by SystemAdmin
  • SystemAdmin
    3545 Posts

    Re: Which artifact to use for describing how a system is built ?

    Q1: If you follow RUP, you would write use cases describing the system as a black box and then write use-case realizations, describing how the system realizes the behavior specified by the use case.

    A sequence diagram is not a RUP artifact, but is commonly used as a part of the artifact "use-case realization".

    Q2: You may combine different scenarios in one use case, by using alternative flows. Activity diagrams are often helpful to give an overview of all alternative flows of a use case.