Re: [Ampu-dev] Some more architecture docs

[alfred . differ]

The source column on the templates refers to the individual who wrote the
related text.  Imagine someone comes along several months later and has a
question about the meaning of some term.  Who would they contact?

When the text gets edited, the source may get more than one name.  The
first name is the primary contact.  The second and later names are to
record secondary contacts incase the first one doesn't understand some of
the changes.  If text is rewritten enough, the source names may completely
change.

On my project, the policy goes something like this...

--------------------------------------------------------------------------------
Policy regarding name credit in requirements, design and development
documentation.

Some lines of the supporting documentation show the name of the project
participant who contributed a definition, description, or iteration.  These
names are present to help readers identify the primary contact person for
questions about content and to give some credit for the work done.  When
another person changes a previous section, their name should be added to the
credit and possibly replace the original author.  Rough guidelines for how to
handle these changes are as follows.

     1.   If the change is mostly editorial in manner, no authorship change 
should
     be made.
     2.   If the change is an alteration of the part leaving most of the content
     intact, the second author's name should be appended to the first making a
     comma separated list.
     3.   If the change is sufficiently large that the primary author may no
     longer be the subject matter expert but may still know enough to help a
     curios reader, the second author's name should be prepended to the first
     making a comma separated list.
     4.   If the change is large enough that the primary author really has
     nothing to do anymore with the new content, the second author's name should
     replace the first.

Remember that the real purpose of the name credits in SailAway documentation is
to provide readers with a point of contact that could answer detailed questions.

--------------------------------------------------------------------------------

When it comes to implementation details, don't worry too much.  The best way to 
refrain from them in the requirements phase is to have
a non-technical badger you for being incomprehensible.  8)   If you write too 
much implementation stuff here, you just get to remove it and
put it in the design documentation later anyway.  You probably won't have to 
throw it away, but you probably will get to rewrite it more often
than you would if you waited for the next phase.

Most developers do it anyway.  If your audience is developers, there is no real 
harm, just extra work for you that you may not realize you
can avoid.

-al