| <!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="img4.html"><img src="left.png" border=0 alt="Précédent"></a> <a href="img6.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="text5.html"><img src="text.png" border=0 alt="Texte"></a></center><br> |
| <img src="img5.png" alt="" style="float:left"/> |
| |
| <p style="direction:ltr;">But that is the inconvenient truth about high-level documentation, and I think any developer who had to maintain this kind of doc up-to-date with |
| the changes made on their software will agree : |
| <b>high-level doc update is quite a burden</b>. When you make a modification on the code, |
| how many of you take the time to browse through the hundred of pages of documentation just to find where to document the changes, and check the whole doc consistency afterward |
| ? </p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">No one, and thus <b>documentation becomes useless</b>, as it does not reflect the recent changes you made on your software. |
| Sooner or later, no one will read it any more, and the design choices your team made will vanish, |
| although you spent a lot of time trying to document these choices. This has direct impacts on productivity and code quality: |
| most of the time spent on the software is then dedicated to browsing through it, doing changes and testing those just to figure out the implications of the change.</p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">You obviously broke the stakeholder Return on investment rule: on one hand, your document brings less and less benefits to the reader, who will start to mistrust the infos, and on the |
| other hand your maintenance cost increases.</p> |
| <p> |
| Your document simply stops being Agile, since you're not able to make it easily react to changes. |
| </p> |
| |
| </p> |
| </body> |
| </html> |
