こんにちは。森田です。
ArgoUML を見ていたら面白いメールが転送されてきたので、
紹介しようと思いたちました。(転送の転送です)
"Can Documentation Be Agile?" というタイトルで、
Agile Modeling の newsletter らしいです。
次のような 12 のプラクティス(？)が提案されています。
1.顧客を焦点にする(Focus on the customer.)
2.十分にシンプルに、しかしシンプルすぎず
(Keep it just simple enough, but not too simple.)
3.顧客を満足される(The customer determines sufficiency. )
4.目的のあるドキュメント(Document with a purpose.)
5.ドキュメントをコミュニケーションに使わない
(Prefer other forms of communication over documentation.)
6.ドキュメントの置き場所を適切に
(Put documentation in the most appropriate place.)
7.ドキュメントを書くタイミングを待つ
(Wait for what you are documenting to stabilize. )
8.モデルは皆がわかるようにする(Display models publicly.)
9.今のモデルをドキュメント化する(Document current models first.)
10.何が必要なドキュメントなのかはっきりさせる
(Require people to justify documentation requests. )
11.量はできるだけ少なく、重複も少なくする。
(Write the fewest documents with the least overlap.)
12.やり手のモノカキを頼る(Get help from an experienced writer. )
---- 以下転送部分 ----
From: "Arnold, Curt" <Curt.Arnold@....com>
To: "'dev@....org'" <dev@....org>
Date: Fri, 19 Oct 2001 08:26:17 -0600
MIME-Version: 1.0
X-Mailer: Internet Mail Service (5.5.2653.19)
Content-Type: text/plain;
charset="iso-8859-1"
Subject: [argouml-dev] FW: SD's Agile Modeling: Can Documentation Be Agile?
Notice the upcoming article on OCL. Definitely should check that aweber@....com is aware of ArgoUML and Poseidon's support for OCL before. Though I never got to OCL nirvana, support for OCL
was one of the things that attracted me to ArgoUML initially. Do we have any web pages that describe our OCL support and how to use it?
-----Original Message-----
From: Agile Modeling
To: curt.arnold@....com
Sent: 10/19/01 8:00 AM
Subject: SD's Agile Modeling: Can Documentation Be Agile?
Welcome to the Agile Modeling newsletter, edited by Software Development
Senior Contributing Editor Scott Ambler. This monthly e-mail newsletter
is a free service for subscribers to Software Development magazine and
SD Online. If you do not wish to receive this newsletter, please follow
the unsubscribe directions at the bottom of this message.
**************advertisement********************
===============================================
Flamenco Networks
===============================================
Looking at Web services? See the Flamenco Web services network and learn
how to cut time and costs of implementing business-class Web services by
up to 80%.
Visit
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQtgaa9GOcH
b/ and download the white paper, "Web Services and the Need for Web
Services Networks."
===============================================
***********************************************
Can Documentation Be Agile?
Software developers often see documentation as a scourge, an unnecessary
burden that must be borne in order to deliver a system. In my
experience, however, documentation doesn't have to be dysfunctional. In
fact, documentation can be quite effective and arguably agile in its
application--if you choose to make it so. Here are 12 steps you can take
to ensure your documentation is agile:
1. Focus on the customer. Identify who will use your documentation
and what they believe they require. Then negotiate with them to
determine the minimal subset that they actually need.
2. Keep it just simple enough, but not too simple. The best
documentation is the simplest that gets the job done. When creating
documentation, follow AM's principle, Use the Simplest Tools (
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8va9GOcH
b/ ), and its practices, Create Simple Content and Depict Models Simply
(
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8wa9GOcH
b/ ).
3. The customer determines sufficiency. As the documentation's
author, you should ensure that it has meaning and provides value; your
customer's role is to validate that you have done so.
4. Document with a purpose. Create a document only if it fulfills a
clear, important and immediate goal of your overall project.
5. Prefer other forms of communication over documentation.
Documentation supports knowledge transfer, but it's only one of several
methods of communication. Often, alternative options may be more useful.
6. Put documentation in the most appropriate place. Where will
someone want a piece of documentation? Varying projects require
different types of documentation. For example, a design decision is best
documented in the code when programmers are the primary audience, is
best added as a note on a diagram when the primary audience is a
designer, or is best placed in an external document when the audience
includes management.
7. Wait for what you are documenting to stabilize. Delay the
creation of all documents as long as possible, creating them just before
you need them. For example, system overviews are best written as you
near a product's release, because by that time, you know what you've
actually built.
8. Display models publicly. When you publicly display models--on a
whiteboard, corkboard or internal Web site--you're promoting transfer of
information and communication. More communication leads to less detailed
documentation, because people are already aware of the basic information
they've gleaned from your model.
9. Document current models first. If you keep a model up-to-date,
it's probably valuable--and therefore worthy of documentation.
10. Require people to justify documentation requests. Ask your
customers what they intend to use the documentation for and how they
will actually use it. Their answers will often reveal that some
documentation functions only as a security blanket. There are much
better way ways to address fear than by providing superfluous
documentation.
11. Write the fewest documents with the least overlap. Try to build
larger documents from smaller ones. I once worked on a project in which
all documentation was written as HTML pages, with each page focusing on
a single topic. This process defined information in one place and one
place only, so there was no opportunity for overlap.
12. Get help from an experienced writer. Technical writers know how
to organize and present information effectively. Also, write
documentation with a partner--just as pair programming can provide
significant value (
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8xa9GOcH
b/ ), "pair documenting" can be equally effective.
Recent Discussions on the Agile Modeling Mailing List:
Whither Object Constraint Language (OCL)?
The Object Management Group (OMG),
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8ya9GOcH
b/ , promotes OCL as a simple, formal language to be used in conjunction
with its Unified Modeling Language (UML). First introduced in the
mid-1990s, the OCL has been all but ignored by the software development
industry. Consensus on the mailing list is that, currently, there is a
severe lack of tool support for OCL, the language isn't readable by
project stakeholders and is therefore inappropriate for requirements
specification, and developers are more motivated to learn programming
languages such as Java and C# instead of formal languages such as OCL, Z
or VDM++. My January 2002 column in Software Development (
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8za9GOcH
b/ ) will explore OCL in greater detail.
Big Design Up Front (BDUF) vs. Emergent Design
Do you invest the time up-front to create a detailed model before you
build something, or do you iteratively model, code and test your
application in an incremental manner, allowing your design to emerge
over time? This is clearly one of the fundamental "religious issues"
within the modeling community, and the debate still rages on the AM
mailing list. Do you make the fundamental trade-off of accepting the
risk of modeling something that's more robust than you currently need,
thereby incurring the expense of overbuilding your software? Or do you
trust that you can refactor your software when you need to support new
requirements as they arise? Both approaches have their risks and
rewards--which do you prefer?
Refactoring Persistence
A thread that spun off from the BDUF discussion focused on the
difficulty of refactoring persistence-related items like the physical
schema of a database. Relational databases are often highly coupled,
both internally (through stored procedures, indices and foreign keys)
and externally (to application software). This high degree of coupling,
along with the poor encapsulation typical of most databases, makes them
difficult to refactor, because one small change to your database can
ripple through dozens of applications. Our discussion focused on the
issues pertaining to refactoring persistence as well as techniques to
make this effort easier. We discussed the use of a persistence
framework/layer, effective mapping strategies, effective data conversion
strategies and ways for developers and DBAs to work together.
The September 11th Fund of the United Way
I'll give two online presentations about Agile Modeling on Friday,
November 30th. The cost is $25, and all proceeds will be donated to the
United Way's September 11th Fund. For details, visit
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Aa9GOcH
b/ --hope you decide to get involved.
**************advertisement********************
===============================================
Dr. Dobb's Journal
===============================================
*** GET 2 EXTRA ISSUES OF DDJ - 14 issues for the price of 12 ***
Dr. Dobb's Journal is the magazine professional programmers have relied
upon for over 25 years. Start benefiting today from DDJ's
uncompromising technical information and platform- and
language-independent articles.
Request a subscription at
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQtgba9GOcH
b/ --your discount keycode is 2dam.
Get 2 extra issues and save 71% off the newsstand price (14 issues for
the price of 12).
===============================================
***********************************************
Suggested Links:
Agile Documentation
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Ba9GOcH
b/
This essay explores critical issues in effective document creation,
including valid and invalid reasons for creating documentation, what
"agile documentation" and "traveling light" really mean, and how can you
make this advice work for you in practice.
Agile Modeling Feedback Page
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Ca9GOcH
b/
This page offers instructions for joining the mailing list, as well as
archived messages.
Alistair Cockburn's Home Page
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Da9GOcH
b/
Alistair provides insights into issues such as communication, agile
software development and software process improvement. You can also
download a PDF draft of his latest book.
Communication
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Ea9GOcH
b/
This essay discusses the various means of communication available to
software developers, comparing and contrasting their effectiveness.
Mapping Objects to Relational Databases
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Fa9GOcH
b/
This paper describes techniques for using objects and relational
databases together, exploring some of the issues that make persistence
refactoring of relational databases difficult.
Refactoring Home Page
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Ga9GOcH
b/
Santa Fe Institute
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQs8Ha9GOcH
b/
This site hosts a large collection of papers, several of which address
the concept of emergence and evolutionary development.
GET THE MAGAZINE
If you are a professional software developer, you may qualify for a free
subscription.
Find out more at
http://click.softwaredevelopment.email-publisher.com/maaadQKaaQtgca9GOcH
b/
ADVERTISING INFORMATION
For more information on advertising in Software Development Newsletters,
contact Kristy Mittelholtz at (415) 947-6189 or by e-mail at
kmittelh@....com.
FEEDBACK AND PROBLEMS
Send letters to the editor to aweber@....com.
Send technical questions or problems to webmaster@....com.
AGILE MODELING is a monthly newsletter brought to you by CMP Media LLC,
publisher of Software Development magazine.
To stop receiving this newsletter, go to
http://softwaredevelopment.email-publisher.com/u/?a84BTw.a9GOcH
Copyright 2001 CMP Media LLC
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@....org
For additional commands, e-mail: dev-help@....org