Win a copy of Design for the Mind this week in the Design forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Documentation Glossary

 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi,

is there something like a documentation glossary, as what kind of documentations exists, with a short description what these documents pretend to be. I found often myself struggling in my german speaking world with anglo-saxon documentation names and do not know what the customer really means by it .

So a list of all kinds of documentation would really help.

Any hints are welcome .

Regards,
Darya
[ June 30, 2005: Message edited by: Darya Akbari ]
 
Ilja Preuss
author
Sheriff
Posts: 14112
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Something like http://www.agilemodeling.com/artifacts/ ?
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think more about a collection of useful/useless documents like the following:

  • Contract
  • Letter of Intent
  • Software Requirement Specification
  • User Manual
  • ??? what else documents do you know ???


  • I appreciate if you list more documents that are typically used for the software development process.

    At the end I would like to filter out only those documents that are confirm with the Agile process and must documents for Agile.

    Regards,
    Darya
     
    Stan James
    (instanceof Sidekick)
    Ranch Hand
    Posts: 8791
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    The link Ilja provided sounds precisely like what you're asking for ... though maybe not what you're hoping for. As far as the Agile "must" list, agile teams seem to get along fine with a box of index cards for stories and anything else they want to track for a while, plus a few Big Visible Charts. Read up some more on agile and see how many documents you find.

    I seem to recall Scott had a wider version of this list with columns like "common usage" and "common misuse". I really liked the abuse column.

    Most of us are pretty geeky code jocks, and think things like "contracts" may be interesting to project managers but are not really related to software. I'm sure you could find more project management oriented sources for such things.
    [ June 30, 2005: Message edited by: Stan James ]
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi Ilja and Stan,

    thanks for your both response. I found what I was looking for under
    Agile Documentation (Types of Documents)

    Regards,
    Darya
     
    Stan James
    (instanceof Sidekick)
    Ranch Hand
    Posts: 8791
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Glad you found that. I had a feeling we weren't talking about the same thing.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Maybe Ilja can help me to map and translate the english document names into according german document names .

    Ilja, I assume you are a native german speaker.

    Regards,
    Darya
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi,

    Unfortunately only german speaker can answer this question . How would you translate these german terms into anglo-saxon Agile terms:

  • Lastenheft
  • Pflichtenheft

  • But let me describe to non-german speaker what is commonly meant by these two terms (I have lot other ). Maybe Agile says to forget about them. Then it would be great you let me know .

    Here it goes:

  • Lastenheft: document mostly provided by the customer which contains the project's functional range and the requirements (from customer's view). Or in short: What do I want to have?
  • Pflichtenheft: document based on the Lastenheft which describes the customer's requirements through workflows, necessary business objects, necessary dialogs. Or in short: How does my solution architecture looks like? What processes are supported and what functions are being realised?


  • Regards,
    Darya
    [ July 01, 2005: Message edited by: Darya Akbari ]
     
    Scott Ambler
    author
    Ranch Hand
    Posts: 608
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    You might find Artifacts for Agile Modeling to be interesting as it suggests when and when not to create an artifact.

    I need to be spectacularly clear about one thing: There is no one right answer as to what is a required set of artifacts. It depends on your situation. That's why spending some time reading The Principles of AM and The Practices of AM is beneficial. You need to understand Multiple Models so that you can Apply the Right Artifact(s) for your situation and create models which are good enough for your situation.

    - Scott
     
    Ilja Preuss
    author
    Sheriff
    Posts: 14112
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Originally posted by Darya Akbari:
    Unfortunately only german speaker can answer this question . How would you translate these german terms into anglo-saxon Agile terms:


    I don't know how I would translate them, but there is some discussion on them here: http://dict.leo.org/cgi-bin/dict/urlexp/20030704132818

    Notice that these terms are in no way intrinsicilly Agile. Agility comes into play when you decide wether and how to do them. To be Agile, you want them to be as lightweight, iterative and "just in time" as possible.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi Scott, Ilja and Stan

    thanks for all the links, I'll definitely read them. To best describe my situation I would describe it with:

    To do the splits between traditional german software engineering (waterfall) and the new anglo-saxon Agile approach.

    I hope not to become overstretched by it .

    Nevertheless, if some german speaker arrive to this thread let me know how you would translate it.

    Regards,
    Darya
    [ July 01, 2005: Message edited by: Darya Akbari ]
     
    Stan James
    (instanceof Sidekick)
    Ranch Hand
    Posts: 8791
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Scott, Artifacts for Agile Modeling was the one I was trying to remember. I spent some time trying to hammer that down to a printable size and gave up. Let us know if you ever make a PDF version.
     
    Ilja Preuss
    author
    Sheriff
    Posts: 14112
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Originally posted by Darya Akbari:
    To do the splits between traditional german software engineering (waterfall) and the new anglo-saxon Agile approach.


    Can you tell us more about what you try to do, what your goal is?
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi Ilja,

    I try to explain why I came up with the idea for an documentation glossary.

    We are a mid size consulting company and try to setup a standard wording for a collection of software engineering terms that we already use over a period of time and which we like to standardise for our contracts and for our internal use in the company.

    Since we operate internationally we want get rid off the german terms we are using right now and replace them with their english counter parts.

    At the same time we are open to move from our waterfall development process to the Agile development process.

    I want to bring these documentation names (waterfall and Agile) in one sheet and discuss them internally. Maybe we are able not only to find the english terms for our new contracts but also to change our methodology from waterfall to agile.

    Whatever we decide we need the english terms for it. Now in case of Agile, Scott has this wonderful page about Agile's document types which I'll bring into my sheet. But to be complete I also want to bring in the waterfall terms.

    Hope that is clear enough

    In the meantime I found at IEEE these terminology for the german waterfall documents:

  • Lastenheft = System Definition Document, sometimes known as the user requirements document or concept of operations.
  • Pflichtenheft = Software Requirements Specification

  • Regards,
    Darya
    [ July 01, 2005: Message edited by: Darya Akbari ]
     
    Ilja Preuss
    author
    Sheriff
    Posts: 14112
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I see, thanks for the elaboration.

    Note that just using Agile terms or producing "Agile documents" isn't going to help you *become* more Agile. The move to Agility is mainly a change in *values* and needs a fundamental change in how you think about your work - especially if you are currently doing waterfall.
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Hi all,

    I need some clarification on the scope of Agile Modeling (AM). It says:


    AM’s focus is on effective modeling and documentation


    Now with respect that I want to use Feature Driven Development (FDD) as my development method, isn't it also a demand of FDD to provide an effective modeling .

    Regards,
    Darya
     
    Scott Ambler
    author
    Ranch Hand
    Posts: 608
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Stan wrote:
    Scott, Artifacts for Agile Modeling was the one I was trying to remember. I spent some time trying to hammer that down to a printable size and gave up. Let us know if you ever make a PDF version.


    Actually, there's a printed version called The Object Primer 3rd Edition: AMDD With UML 2.

    The original draft version of the modeling portions of the book were published at those pages. The book is a little more up to date in places, and a couple of new pages have been added since the book came out, but for the most part they're pretty much the same. The Object Primer 3rd Edition was written with the goal to be the sister book to Agile Modeling: Effective Practices for XP and the RUP.

    - Scott
     
    Scott Ambler
    author
    Ranch Hand
    Posts: 608
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Darya said:

    I need some clarification on the scope of Agile Modeling (AM). It says:
    AM�s focus is on effective modeling and documentation. Now with respect that I want to use Feature Driven Development (FDD) as my development method, isn't it also a demand of FDD to provide an effective modeling.


    The section The Scope of AM
    describes the concept that the principles and practices of AM should be tailored into a base process, such as XP, RUP, ... One such base process would be FDD. AM would guide you towards greater effectiveness with respect to modeling and documentation on an FDD project.

    A few years ago I wrote Agile Modeling and FDD for my AM newsletter. I've been thinking about updating it and rehosting it on the AM site, but haven't gotten to it yet.

    - Scott
     
    Darya Akbari
    Ranch Hand
    Posts: 1855
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    I'm going to attend an FDD certification workshop from Jeff De Luca and I appreciate any update concerning AM and FDD to get a precise orientation .

    Regards,
    Darya
     
    • Post Reply
    • Bookmark Topic Watch Topic
    • New Topic