Loading ...
Sorry, an error occurred while loading the content.
 

RE: [agile-usability] Re: documenting the UI in an agile environment

Expand Messages
  • Desilets, Alain
    This is a different level of documentation, but I find nowadays, I mostly document my code by: A) Using long and verbous but highly communicative names for
    Message 1 of 15 , Dec 1, 2005
      Message
      This is a different level of documentation, but I find nowadays, I mostly document my code by:
       
      A) Using long and verbous but highly communicative names for classes, variables and methods. It's not uncommon for me to spend 2 minutes thinking about what the best name is for a method. It's also common for me to change the name of that method half a dozen times over the course of its life, to keep the name in synch with changes in its actual functionality.
       
      B) Writing unit tests that read as a sequence of examples. For example, I once wrote a small "searh engine" to index words contained in a string. The list of tests for that class looked something like this:
       
      test_This_is_how_you_create_a_WordIndex
       
      test_You_can_use_WordIndex_to_index_and_retrieve_documents_based_on_their_word_content
       
      test_In_the_contents_of_the_document_words_are_delimited_by_non_alphanumeric_characters
       
      test_Indexing_and_retrieval_are_case_insensitive

      test_You_can_define_stop_words_which_are_ignored_in_retrieval
       
      test_WordIndex_deals_correctly_with_French_content()
       
      etc...
       
      Each of those was the name of a test method. The code for each test method was a small snippet of code that provides an example of how to do use WordIndex to carry out a particular task. For example, the code for the second test method might read something like this:
       
       public void test_You_can_use_WordIndex_to_index_and_retrieve_documents_based_on_their_word_content() {
        index = new WordIndex();
        index.indexDocument("doc1", "this string is the content of the first document");
        index.indexDocument("doc2", "this string is the content of the second document");
       
        HashSet retrievedDocuments = null;
       
        retrievedDocuments = index.retrieveDocsWithAllWords(new String[] {"first", "content"});
        assertEquals("Wrong set of documents was retrieved", justDoc1, retrievedDocuments);
       
        retrievedDocuments = index.retrieveDocsWithAllWords(new String[] {"content"});
        assertEquals("Wrong set of documents was retrieved", doc1AndDoc2, retrievedDocuments);
      }
       
      The beauty of this approach is that the examples provided by the TestCase are garanteed to be correct, because I run them hundreds of times of day, and fix any bug they reveal as soon as I find them.
       
      I find with these two techniques (meaningful names and readable example-like test cases), I can limit my documentation to "code maps", i.e. simplified maps that explain at a very high level how certain parts of the code hang together. I only do this for parts of the code that are complex and hard to understand.
    • Desilets, Alain
      I find with these two techniques (meaningful names and readable example-like test cases), I can limit my documentation to code maps , i.e. simplified maps
      Message 2 of 15 , Dec 1, 2005
        Message
        I find with these two techniques (meaningful names and readable example-like test cases), I can limit my documentation to "code maps", i.e. simplified maps that explain at a very high level how certain parts of the code hang together. I only do this for parts of the code that are complex and hard to understand. 
         
        -- Alain:
        Oh, and of course, I write those code maps on a wiki site. As Jade points out, wikis are great!
        ---- 
      • Jade Ohlhauser
        We use MediaWiki, the same software powering Wikipedia. http://www.mediawiki.org/wiki/MediaWiki http://en.wikipedia.org/wiki/Main_Page Pros * Fast setup *
        Message 3 of 15 , Dec 1, 2005
          We use MediaWiki, the same software powering Wikipedia.
           
           
           
          Pros
          * Fast setup
          Mature, robust, and well tested
          Easy CSS customization
          Free as in beer and free as in speech
          Flexible markup for formatting
          * Style is handled centrally by CSS
          * Complete edit history & visual dif
           
          Cons
          Limited depth in access control
          Proprietary markup for formatting
          * No sophisticated "multiple users edit same page" handling. At least there's the history (undo) and the ability to limit edits to one section (lessen change of "collision")
           
          For us that first con isn't a big deal because we have a small company so 3 levels of access is fine. The second con isn't a problem for us either because our primary contributors are coders and other technical people so the markup, while possibly challenging to non-programmers, is not an issue. Also, we're somewhat comforted because both those issues are being addressed by ongoing MediaWiki development and that since it's open source if we had to grow quickly beyond its current capabilities we could maybe make improvements ourselves or by contract. In fact, I think version 1.5 out now has user account groups. The cons can also be improved today with extensions/code modification. The whole formatting issue is a pro and a con because once you learn the code you have a lot of control. As mentioned, it works out good for us because the programmers have naturally become interested in the details of it.
           
          We had never setup any wiki before, but our DBA had it on the server in minutes and it took me about 2 hours to blend it into our website design by modifying the existing CSS and PHP files. It took me another couple hours to setup the users including adding an extension to give me more user options.
           
          As for getting people to contribute, it was mostly a matter of getting them comfortable. At the beginning that meant some mandatory contributions both original and transfers of old docs. One of the nice things about the wiki is it removes the burden of styling and organizing content so people can concentrate on content. Also, the developers and testers soon saw the benefit of the new system and how the more they added, the more benefit they personally got. That really helps. We use some contractors and they've also commented on how great this new system is.
           
          Jade Ohlhauser
          Product Manager
          RPM Software                                 
          www.rpmsoftware.com 403-265-6727 x704
           


          From: agile-usability@yahoogroups.com [mailto:agile-usability@yahoogroups.com] On Behalf Of William Pietri
          Sent: Wednesday, November 30, 2005 4:14 PM
          To: agile-usability@yahoogroups.com
          Subject: Re: [agile-usability] Re: documenting the UI in an agile environment

          Jade Ohlhauser wrote:
          We've moved all documentation to a single wiki. [...] Having been using this "new way" for several months now, everyone involved agrees this is a total improvement in every way. [...]
           In the old system even if if we could have increased the volume some how, it would have been a waste. Those words would have sat trapped in a word file in some folder no one will ever read. In the wiki all this content is usable with a fast, wide search and easy linking. Updates and minor fixes are a breeze with anyone able to login and fix things. We also have easy control over access to hide certain content from certain people.
           
          To me this is like when I first experienced defect racking or source control, I can't imagine going back to not using it. Your mileage may vary.
           

          That's exciting to hear. Which wiki package did you use? And are there particular tricks you folks used to get everybody using the wiki?

          Thanks,

          William
        Your message has been successfully submitted and would be delivered to recipients shortly.