Search code examples
architecturecode-documentationarc42

Should I document the current context and scope too


I am currently writing an arc42 specification document for an application that is supposed to replace several convoluted manual processes.

In the documentation as well as the examples I noticed, that "Context and Scope" normally only includes the context and scope of the application to be developed.

Should I also include a diagram of the current process as well? Personally I believe that showing the differences between the "before" and "after" state of an application would be helpful to include.


Solution

  • arc42 shall help communicate and document software architectures - so everything that supports understanding might be included.

    "Scope and Context" show the system plus its immediate neighbours, containing all external interfaces. I suggest to use a diagram plus a table - as proposed in the documentation of arc42-section-3

    In arc42, you often have the choice where (and how) to convey information, therefore we created a fairly extensive docs.arc42.org and faq.arc42.org site for it.

    Depending on your choice of tools and the kinds of information already available, I see a few options or aspects:

    1. Use the current manual processes as motivation for the new system

    The "manual processes" you mentioned might be a strong motivation to create the new system. Therefore, you might describe a few disadvantages or issues of these manual steps right in section 1.2 (Introduction/Motivation).

    2. Split section 3 (Context) in "Prior" and "New"

    If these "manual processes" relate to external interfaces, you might create a section 3.1 describing the current situation with its downsides)

    In 3.2 you could then propose or specify the new system with improved or automated processes.

    3. "Manual Processes" could be shown under "6. Runtime View"

    A "process" is comprised of a series of steps or activities - and as such can be part of the arc42 runtime view.

    4. Delegate "Manual Processes" to another type of documentation

    You might create a "Review of the current situation" document, describing the current situation with the "manual processes" and related problems and risks.

    In this case, you would avoid bloating your arc42 architecture documentation with information that's not directly related to the design, construction and implementation of the new system.