This week's book giveaway is in the Servlets forum.
We're giving away four copies of Murach's Java Servlets and JSP and have Joel Murach on-line!
See this thread for details.
The moose likes Agile and Other Processes and the fly likes Documentation Glossary Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Murach's Java Servlets and JSP this week in the Servlets forum!
JavaRanch » Java Forums » Engineering » Agile and Other Processes
Bookmark "Documentation Glossary" Watch "Documentation Glossary" New topic
Author

Documentation Glossary

Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
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 ]

SCJP, SCJD, SCWCD, SCBCD
Ilja Preuss
author
Sheriff

Joined: Jul 11, 2001
Posts: 14112
Something like http://www.agilemodeling.com/artifacts/ ?


The soul is dyed the color of its thoughts. Think only on those things that are in line with your principles and can bear the light of day. The content of your character is your choice. Day by day, what you do is who you become. Your integrity is your destiny - it is the light that guides your way. - Heraclitus
Darya Akbari
Ranch Hand

Joined: Aug 21, 2004
Posts: 1855
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

    Joined: Jan 29, 2003
    Posts: 8791
    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 ]

    A good question is never answered. It is not a bolt to be tightened into place but a seed to be planted and to bear more seed toward the hope of greening the landscape of the idea. John Ciardi
    Darya Akbari
    Ranch Hand

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Jan 29, 2003
    Posts: 8791
    Glad you found that. I had a feeling we weren't talking about the same thing.
    Darya Akbari
    Ranch Hand

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Dec 12, 2003
    Posts: 608
    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


    <a href="http://www-306.ibm.com/software/rational/bios/ambler.html" target="_blank" rel="nofollow">Scott W. Ambler</a><br />Practice Leader Agile Development, IBM Rational<br /> <br />Now available: <a href="http://www.ambysoft.com/books/refactoringDatabases.html" target="_blank" rel="nofollow">Refactoring Databases: Evolutionary Database Design</a>
    Ilja Preuss
    author
    Sheriff

    Joined: Jul 11, 2001
    Posts: 14112
    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

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Jan 29, 2003
    Posts: 8791
    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

    Joined: Jul 11, 2001
    Posts: 14112
    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

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Jul 11, 2001
    Posts: 14112
    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

    Joined: Aug 21, 2004
    Posts: 1855
    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

    Joined: Dec 12, 2003
    Posts: 608
    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

    Joined: Dec 12, 2003
    Posts: 608
    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

    Joined: Aug 21, 2004
    Posts: 1855
    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
     
    Don't get me started about those stupid light bulbs.
     
    subject: Documentation Glossary
     
    Similar Threads
    B&S: What to include into user documentation
    Software Architecture: Industry x State of the Art
    Got It, Passed SCJD with 400/378, Thanks!
    B&S: Javadoc in Sun's data interface allowed?
    can anyone explain or give link how dynamic link library works?