| <!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="img2.html"><img src="left.png" border=0 alt="Précédent"></a> <a href="img4.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_ece2011.htm"><img src="home.png" border=0 alt="Résumé"></a> <a href="text3.html"><img src="text.png" border=0 alt="Texte"></a></center><br> |
| <img src="img3.png" alt="" style="float:left"/> |
| <p><p style="direction:ltr;">First of all, let us ask a simple question : why do we write doc ? </p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">Well it's quite simple : we write doc to communicate efficiently with our team and to remember the decisions we made.</p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">When we write a documentation, more than the code itself we would like our reader to understand the spirit behind it : |
| what main concerns and requirements made us choose the current architecture ?</p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;"> I should not have to stress out how important it is that everyone understand these Intents behind softwares : </p> |
| <p style="direction:ltr;">- first of all, when your team grows up, newcomers should quickly understand your software architecture and how to |
| properly extend it, to be able to maintain and improve your software (which is basically what they are paid for). |
| You don't have the time to explain all these choices by yourself, so documentation is a perfect way to do it.<br/>- What is more, I challenge you to explain clearly the design choices you made on a project six months ago ; |
| I am sure that you will forget an important concern.</p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">To capture such intents, we can use many kind of doc format : </p> |
| <p style="direction:ltr;">- Javadoc is great to explain what a Package / Class / method is about.<br/> |
| However, its <b>scope is too narrow</b> to present high-level considerations : how would I explain the design choices I made or a functional requirement when focusing on a Java Class ? I see the tree, but where is the forest ?</p> |
| <p style="direction:ltr;">- Models are great to capture constraints and formalize design.<br/>But we have the same issue here: with a formal structure, |
| you cannot properly split your explanations across concerns or functional requirements. </p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;">That is why what I call <b>high-level documentation</b> (such as textile files, Latex or Open Office documents) is a much better fit for this task : </p> |
| <p style="direction:ltr;"> its structure allows to present each concern in one specific chapter or section. In result, a reader will be able to discover the software step by step, with a bird-eye view of each main requirements and design decision. </p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;"></p> |
| <p style="direction:ltr;"></p> |
| |
| </p> |
| </body> |
| </html> |
