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

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

Expand Messages
  • William Pietri
    ... 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
    Message 1 of 15 , Nov 30, 2005
    • 0 Attachment
      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
    • 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 2 of 15 , Dec 1, 2005
      • 0 Attachment
        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 3 of 15 , Dec 1, 2005
        • 0 Attachment
          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 4 of 15 , Dec 1, 2005
          • 0 Attachment
            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.