Home > Archive > Software Engineering > December 2005 > Creating Architecture Documents from Existing Application
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Creating Architecture Documents from Existing Application
|
|
| bennett.sean@gmail.com 2005-12-05, 7:03 pm |
| Hi,
we want to create some documentation of the architecture in an existing
ASP application. Can anyone suggest some document types to use to make
it easy to understand the application?
This could be UML type documents or otherwise.
| |
|
|
| Justice4All 2005-12-06, 3:57 am |
| Greetings,
I have two suggestions for you. The first (not a quick one, but
effective in the end) is to read the book ("Documenting Software
Architectures:Views and Beyond", Addison-Wesley, ISBN: 0-201-70372-6).
This is a very comprehensive book that discusses in elaborate detail
how to tailor an Software Architecture document for your audience. It
also gives some useful templates to use for Software Architecture
documentation. Note that the authors are not inventing their own
standards. I've originally got to know this book through the Software
Engineering Institute's (SEI) web site; as it is taught in one of their
courses.
The downside of this option is that you'll spend some considerable time
in order to be able to produce something concrete.
IMHO, the "4+1 View Model of Architecture" is, to a great degree, vague
and broad in the sense that you can't immediately "read it and apply
it".
My other suggestion that will yield quick and fast results will be to
purchase Rational's Unified Process (RUP) documentation templates or
many of those widely available documentation templates. The downside of
this option is that these templates are based on the pure experience
and insight of their creators; not to mention that they are not
standardized (except for the RUP documentation templates which could be
considered a "de facto" standard).
Something that applies to both options is that you will probably have
to tailor any kinds of templates for your own needs.
Regards,
Moataz
| |
| Cristo 2005-12-07, 9:57 pm |
| Dears,
Bennet, I suggest you follow Moataz's first option. I have been working
with the book and it provides a nice, almost complete, example on its
second part. Even you loose some time on the begginning, you should not
use "4+1 View...Architecture" since it is outdated. Moreover "Views &
Beyond" is inspired by Kruchten work for documentation using views...
Hope this helps,
Cristovao
| |
| Mark Woyna 2005-12-07, 9:57 pm |
|
How is "4+1" outdated? Documenting an architecture with a use case,
logical, implementation, process, and deployment views is standard
practice, especially in shops utilizing RUP.
I was referring to the model, not the book. The book may not be
up-to-date, but the 5 views depicted certainly haven't lost their
relevance.
Mark
| |
| Cristo 2005-12-08, 7:58 am |
| Dear Mark,
I'm really sorry, I misunderstood myself. As far as I know, there is no
special book about "4+1" of Kruchten (You pointed the paper in your
first post). This famous paper is dated of 1995, but I agree the 5
views have not lost their relevance. But you need to agree with me that
the 1995 paper is quite theoretic and it's dificult to apply directly,
or am I worng? So, my suggestion was to use the "Views & Beyond", since
it concretely uses the first theory and gives an guide example.
Regards,
Cristovao
| |
| Mark Woyna 2005-12-09, 4:15 am |
| I've used the 4+1 views quite successfully. However, one can not
properly document an architecture with UML diagrams alone. I've
incorporated various other types of textual information into an
architecture document that were not outlined by the 4+1 model.
So, yes, I agree that the original paper was not the final answer. I
noted it simply as a good starting point, but certainly not the only
reference one should consider. I'll have to take a look at "Views and
Beyond" myself.
Ultimately, documenting an architecture is about communicating key
design decisions to your stakeholders, e.g. customers, managers,
developers, testers, marketing, etc., and convincing them that the
approach will fulfill the functional and non-functional requirements.
Mark
|
|
|
|
|