pages/transcripts/2012_AgileALMConnect/img4.html - gerrit/www.eclipse.org/intent - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
      "http://www.w3.org/TR/html4/transitional.dtd">
 <html>
 <head>
   <meta HTTP-EQUIV=CONTENT-TYPE CONTENT="text/html; charset=utf-8">
   <title>Create Useful Documentation with Mylyn Intent : transcript</title>
   <link rel="stylesheet" type="text/css" href="talk.css">
 </head>
 <body text="#000000" bgcolor="#FFFFFF" link="#000080" vlink="#0000CC" alink="#000080">
 <center>
 <a href="img0.html"><img src="first.png" border=0 alt="Première page"></a> <a href="img3.html"><img src="left.png" border=0 alt="Précédent"></a> <a href="img5.html"><img src="right.png" border=0 alt="Suivant"></a> <a href="img29.html"><img src="last.png" border=0 alt="Dernière page"></a> <a href="Intent_AgileALMConnect2012.htm"><img src="home.png" border=0 alt="Résumé"></a> <a href="text4.html"><img src="text.png" border=0 alt="Texte"></a></center><br>
 <img src="img4.png" alt="" style="float:left"/>

 <p><p style="direction:ltr;">
 So we see than instead of discarding documentation, we have to create just enough documentation to get by. Each Document that we judge necessary can only prove useful if they are of high quality.
 We could define an <b>Agile Document</b> as a document checking the following criterias :

 <br/><br/>
 <strong>-</strong> Maximize the <b>Stakeholders Return on Investment</b> :  the benefits provided by an agile document should be greater than the investment in its creation and maintenance
 <br/><br/>
 <strong>-</strong> Be able to <b>Respond to changes</b>. In other words, we must be able to update it whenever the stakeholders need or the software code change.
 It is very important that the few documentation we decided to create is accurate and up-to-date.

 <br/><br/>
 There are different strategies to determine when it is the best time to update documentation :
 <br/><br/>
 - If you follow a <b>Document Late</b> best practice, you will create and update documents as late as possible, often just before you need to actually deliver them.
 This strategy is based on common sense : wait until the information has stabilized before you capture it inside documentation.
 However, you may have a lot of changes to report, and hence you multiply the risk of forgetting to update some parts of the documentation.
 <br/><br/>
 - Another, more disciplined approach, is to <b>Document Continuously</b> as you go.
   The challenge is that any documentation that you write needs to evolve over time in sync with your code.
 <br/><br/>
 - If you follow the <b>Update Only When It Hurts</b> practice, then you will update the documentation only when a reader is being inordinately harmed, including a significant loss of productivity, because the documentation is not up-to-date.


 </p>
 <p>All these practices require to be able to update all the documentations parts related to a given change (in requirement, in design, in code).</p>
 </p>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
	"http://www.w3.org/TR/html4/transitional.dtd">
	<html>
	<head>
	<meta HTTP-EQUIV=CONTENT-TYPE CONTENT="text/html; charset=utf-8">
	<title>Create Useful Documentation with Mylyn Intent : transcript</title>
	<link rel="stylesheet" type="text/css" href="talk.css">
	</head>
	<body text="#000000" bgcolor="#FFFFFF" link="#000080" vlink="#0000CC" alink="#000080">
	<center>
	<a href="img0.html"><img src="first.png" border=0 alt="Première page"></a> <a href="img3.html"><img src="left.png" border=0 alt="Précédent"></a> <a href="img5.html"><img src="right.png" border=0 alt="Suivant"></a> <a href="img29.html"><img src="last.png" border=0 alt="Dernière page"></a> <a href="Intent_AgileALMConnect2012.htm"><img src="home.png" border=0 alt="Résumé"></a> <a href="text4.html"><img src="text.png" border=0 alt="Texte"></a></center><br>
	<img src="img4.png" alt="" style="float:left"/>

	<p><p style="direction:ltr;">
	So we see than instead of discarding documentation, we have to create just enough documentation to get by. Each Document that we judge necessary can only prove useful if they are of high quality.
	We could define an <b>Agile Document</b> as a document checking the following criterias :

	<br/><br/>
	<strong>-</strong> Maximize the <b>Stakeholders Return on Investment</b> : the benefits provided by an agile document should be greater than the investment in its creation and maintenance
	<br/><br/>
	<strong>-</strong> Be able to <b>Respond to changes</b>. In other words, we must be able to update it whenever the stakeholders need or the software code change.
	It is very important that the few documentation we decided to create is accurate and up-to-date.

	<br/><br/>
	There are different strategies to determine when it is the best time to update documentation :
	<br/><br/>
	- If you follow a <b>Document Late</b> best practice, you will create and update documents as late as possible, often just before you need to actually deliver them.
	This strategy is based on common sense : wait until the information has stabilized before you capture it inside documentation.
	However, you may have a lot of changes to report, and hence you multiply the risk of forgetting to update some parts of the documentation.
	<br/><br/>
	- Another, more disciplined approach, is to <b>Document Continuously</b> as you go.
	The challenge is that any documentation that you write needs to evolve over time in sync with your code.
	<br/><br/>
	- If you follow the <b>Update Only When It Hurts</b> practice, then you will update the documentation only when a reader is being inordinately harmed, including a significant loss of productivity, because the documentation is not up-to-date.


	</p>
	<p>All these practices require to be able to update all the documentations parts related to a given change (in requirement, in design, in code).</p>
	</p>
	</body>
	</html>