http://scrumpt.com/blogs/tiagonmas/archive/tags/documenta_E700E300_o/default.aspxTags: documentaçãoenCommunityServer 2007.1 (Build: 20917.1142)http://scrumpt.com/blogs/tiagonmas/archive/2008/05/15/documenta-231-227-o-193-gil.aspxThu, 15 May 2008 17:22:19 GMT428e683f-ac9d-4237-aa9f-68e02ce190fe:171tiagonmas253http://scrumpt.com/blogs/tiagonmas/rsscomments.aspx?PostID=171http://scrumpt.com/blogs/tiagonmas/archive/2008/05/15/documenta-231-227-o-193-gil.aspx#comments <h3 class="post-title entry-title">Um dos principios do <a href="http://agilemanifesto.org/" target="_blank" title="Agile Manifesto"><span style="COLOR:#666699;">Agile Manifesto</span></a> é &quot;Working software over comprehensive documentation&quot;.</h3> <div class="post-body entry-content"> <p>O que faz pensar na questão sobre qual e quanta documentação é que é precisa.</p> <p>Coloquei esta questão ao Mitch Lacey numa entrevista que lhe fiz no início deste ano. A resposta pode ser vista <a href="http://tiagonmas.blogspot.com/2008/03/interview-with-mitch-lacey.html" title="here"><span style="COLOR:#666699;">aqui</span></a>. No entanto, ao ler o livro <a href="http://www.ambysoft.com/books/agileDatabaseTechniques.html" target="_blank" title="Agile Database Techniques"><span style="COLOR:#666699;">Agile Database Techniques</span></a> reparei numa secção sobre documentação que achei muito interessante.</p> <p>Aqui está um resumo (em inglês)</p> <p><!--more--></p> <!--more--> <p>Documentation is an intrinsic part of any system. The creation and maintenance of which is a &quot;necessary Evil&quot;. Liek agile models, agile documents are just barely good enough.</p> <p><strong>A document is agile when it meets the following criteria:</strong></p> <ul> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents maximize stakeholder investment</strong>- The benefit provided by an agile document is greater than the investment in its creation and maintenance.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents are &quot;lean and mean&quot;</strong> - They contain just enough information to fulfill its purpose, in other words it is as simple as it can possibly be. Bullets form is allowed. Content is more important than representation.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents fulfill a purpose</strong>- They fulfill a single defined purpose. If you don&#39;t know why you are creating the document, or the purpose is questionable, then stop and rethink what you are doing.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents describe information that is not likely to change</strong>- The greater the chance that information will change the less value there is in investing significant time writing about it.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents describe &quot;good things to know&quot;</strong>- They capture critical information, information that is not readily obvious.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents have a specific customer and facilitate the work efforts of that customer -</strong> A document written for maintenance developers is different from user documentation or tutorial. Work closely with the customer for your documentation if you want to create something that will meet their needs.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents are sufficiently accurate, consistent and detailed</strong> - Agile documents don&#39;t need to be perfect, they just need to be good enough.</li> <li style="list-style:none;"><br /></li> <li style="MARGIN:0cm 0cm 0pt;"><strong>Agile documents are sufficiently indexed -</strong> Documentation isn&#39;t effective if you cannot easily find the information contained in it.</li> <li style="list-style:none;"><br /></li> </ul> <p>From the book <strong>Agile Database Techniques: Effective Strategies for the Agile Software Developer (Wiley Application Development) (Paperback),</strong> by Scott Amber</p> </div> <img src="http://scrumpt.com/aggbug.aspx?PostID=171" width="1" height="1">documentação