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

documenting the UI in an agile environment

Expand Messages
  • hinson_heyer
    I work in a small development group that is in the process of switching to agile development. As the UI designer for the group, I m new to the company (about 9
    Message 1 of 15 , Nov 28, 2005
    • 0 Attachment
      I work in a small development group that is in the process of
      switching to agile development. As the UI designer for the group,
      I'm new to the company (about 9 months) and have had to introduce a
      template for the UI design specs that didn't previously exist. To
      that end, I've been creating UI specs much like I have previous
      companies in which the UI spec reflects the bigger vision for the
      UI. I indicate any changes in subsequent iterations through track
      changes and detailed information on changes in the document revision
      history and identify those in relationship to a particular
      iteration. In general, our UI specs average no more than 15-20
      pages of flows, screen shots, and documentation. Also the changes to
      the UI that may occur in a given iteration may span multiple specs.

      Recently, however, the software engineering manager has started to
      complain that our specs are too big, and it's too hard for the
      programmers to follow what they need to build for a particular
      iteration. He would prefer "delta" specs for each iteration that
      only contain what is changing for that functionality in that
      particular iteration. My concern is that if we only document
      initially what we determine can be built in an iteration we will
      lose the big picture of what we want the interaction to be.

      So I'm wondering what best practices exist for documenting the UI in
      an agile environment?


      Many thanks!
      Cherie Hinson
    • William Pietri
      ... My general feeling about big pictures is that they can only usefully be kept in people s heads. Will you be sitting in the same room with the team and
      Message 2 of 15 , Nov 28, 2005
      • 0 Attachment
        hinson_heyer wrote:

        >[...] My concern is that if we only document
        >initially what we determine can be built in an iteration we will
        >lose the big picture of what we want the interaction to be.
        >
        >So I'm wondering what best practices exist for documenting the UI in
        >an agile environment?
        >
        >

        My general feeling about big pictures is that they can only usefully be
        kept in people's heads. Will you be sitting in the same room with the
        team and looking at what they're up to at least daily? And is the team
        doing weekly internal releases?

        If so, what are the negative effects that you're concerned about?

        William
      • Jeff Patton
        ... to ... in ... Hmm... I m latching on to one thing you said: It s too hard for the programmers to follow what they need to build for a particular
        Message 3 of 15 , Nov 28, 2005
        • 0 Attachment
          --- In agile-usability@yahoogroups.com, "hinson_heyer"
          <hinson_heyer@y...> wrote:
          > iteration. In general, our UI specs average no more than 15-20
          > pages of flows, screen shots, and documentation. Also the changes
          to
          > the UI that may occur in a given iteration may span multiple specs.
          ...
          > Recently, however, the software engineering manager has started to
          > complain that our specs are too big, and it's too hard for the
          > programmers to follow what they need to build for a particular
          > iteration. He would prefer "delta" specs for each iteration that
          > only contain what is changing for that functionality in that
          > particular iteration.
          ...
          > So I'm wondering what best practices exist for documenting the UI
          in
          > an agile environment?


          Hmm... I'm latching on to one thing you said: "It's too hard for the
          programmers to follow what they need to build for a particular
          iteration." I suspect they're trying to use the document to do that?

          Agile environments are going to place a lot of emphasis on face to
          face communication, collaborating directly with the developers [or at
          least they should]. So, the ideal way to document UI in agile
          environments isn't.

          It's common in an agile environment to introduce work at the
          beginning of an iteration in a planning session where you discuss the
          work/user story with developers and they estimate the work at that
          time. I find that if I'm having a discussion with a developer using
          one of these sorts of documents as an aid, the developer will make
          notes in it and cross out things that don't matter for this
          iteration. We'll often take a highlighter pen to the document to
          mark the things that do matter. If you do this, over time developers
          learn to predict your user interaction patterns, allowing you to
          write a little less, and you get a feel for what information is
          critical for them to understand, allowing you to write a little
          less.

          In an ideal Agile world you might draw something on a white board,
          make big hand gestures, then shoot a digital photograph of it for
          posterity. In practice today I do paper prototyping with old
          fashioned pencil and paper, then photocopy the prototype in various
          stages of workflow to construct a storyboard on poster paper -
          annotated with interaction details. I'll shoot digital photos of
          them to preserve them. [email me offline if you'd like some
          examples.]

          The real point here is that no document, no matter how well written
          can replace face to face collaboration. I'm not sure I'd say that it
          doesn't take 15-20 pages to describe the interactions for a piece of
          user interface, and that it doesn't take a few of these documents to
          describe a coherent view of the user interface. But, I know it's
          tough for anyone, no matter how patient, to distill a stack of these
          things down to what's important to know right now. I think you might
          be able to help them do that faster face to face. Would that work in
          your organization?

          thanks very much for posting!

          -Jeff
        • Jon Meads
          What Cherie might need is an appropriate Style Guide that specifies the basic look and feel for the set of UIs in a family of products or for different
          Message 4 of 15 , Nov 29, 2005
          • 0 Attachment
            What Cherie might need is an appropriate Style Guide that specifies the
            basic 'look and feel' for the set of UIs in a family of products or for
            different modules on a complex product. The Style Guide provides a base for
            consistency. I recommend that the base concepts of a Style Guide be done as
            close to the beginning of the development effort as possible so that the
            overall UI vision can be communicated and agreed upon.

            Then the UI for a specific phase of a development effort may be best
            communicated as a "paper prototype" illustrating the functionality to be
            expressed for that phase. Almost certainly, the UI design for a given
            development phase will change during iterations which means it's best not to
            invest much time in formal specifications (the update cost would be
            excessive). Where appropriate, add to the Style Guide as development
            proceeds and let the Style Guide be the primary specification. Any
            additional UI documentation for a particular development phase should be
            more "design rationale" than specifications.

            Cheers,
            jon

            -----Original Message-----
            From: agile-usability@yahoogroups.com
            [mailto:agile-usability@yahoogroups.com] On Behalf Of Jeff Patton
            Sent: Monday, November 28, 2005 9:19 PM
            To: agile-usability@yahoogroups.com
            Subject: [agile-usability] Re: documenting the UI in an agile environment

            --- In agile-usability@yahoogroups.com, "hinson_heyer"
            <hinson_heyer@y...> wrote:
            > iteration. In general, our UI specs average no more than 15-20 pages
            > of flows, screen shots, and documentation. Also the changes
            to
            > the UI that may occur in a given iteration may span multiple specs.
            ...
            > Recently, however, the software engineering manager has started to
            > complain that our specs are too big, and it's too hard for the
            > programmers to follow what they need to build for a particular
            > iteration. He would prefer "delta" specs for each iteration that only
            > contain what is changing for that functionality in that particular
            > iteration.
            ...
            > So I'm wondering what best practices exist for documenting the UI
            in
            > an agile environment?


            Hmm... I'm latching on to one thing you said: "It's too hard for the
            programmers to follow what they need to build for a particular iteration."
            I suspect they're trying to use the document to do that?

            Agile environments are going to place a lot of emphasis on face to face
            communication, collaborating directly with the developers [or at least they
            should]. So, the ideal way to document UI in agile environments isn't.

            It's common in an agile environment to introduce work at the beginning of an
            iteration in a planning session where you discuss the work/user story with
            developers and they estimate the work at that time. I find that if I'm
            having a discussion with a developer using one of these sorts of documents
            as an aid, the developer will make notes in it and cross out things that
            don't matter for this iteration. We'll often take a highlighter pen to the
            document to mark the things that do matter. If you do this, over time
            developers learn to predict your user interaction patterns, allowing you to
            write a little less, and you get a feel for what information is critical for
            them to understand, allowing you to write a little less.

            In an ideal Agile world you might draw something on a white board, make big
            hand gestures, then shoot a digital photograph of it for posterity. In
            practice today I do paper prototyping with old fashioned pencil and paper,
            then photocopy the prototype in various stages of workflow to construct a
            storyboard on poster paper - annotated with interaction details. I'll shoot
            digital photos of them to preserve them. [email me offline if you'd like
            some
            examples.]

            The real point here is that no document, no matter how well written can
            replace face to face collaboration. I'm not sure I'd say that it doesn't
            take 15-20 pages to describe the interactions for a piece of user interface,
            and that it doesn't take a few of these documents to describe a coherent
            view of the user interface. But, I know it's tough for anyone, no matter
            how patient, to distill a stack of these things down to what's important to
            know right now. I think you might be able to help them do that faster face
            to face. Would that work in your organization?

            thanks very much for posting!

            -Jeff





            ------------------------ Yahoo! Groups Sponsor --------------------~--> Get
            fast access to your favorite Yahoo! Groups. Make Yahoo! your home page
            http://us.click.yahoo.com/dpRU5A/wUILAA/yQLSAA/dpFolB/TM
            --------------------------------------------------------------------~->


            Yahoo! Groups Links
          • Cherie Hinson
            To add an additional twist to my original posting, the challenge we face in this company is that our development group is in Hungary. And currently they re
            Message 5 of 15 , Nov 29, 2005
            • 0 Attachment
              To add an additional twist to my original posting, the challenge we face in this company is that our development group is in Hungary.  And currently they're building the iteration AFTER we do the initial design.  Because of the language barrier, communication between groups doesn't happen as often as it should, and is generally filtered through the development manager.
               
               
            • William Pietri
              ... Because off-the-shelf agile development makes heavy use of in-person and tacit communication. distributed agile development will require various
              Message 6 of 15 , Nov 29, 2005
              • 0 Attachment
                Cherie Hinson wrote:

                > To add an additional twist to my original posting, the challenge we
                > face in this company is that our development group is in Hungary. And
                > currently they're building the iteration AFTER we do the initial
                > design. Because of the language barrier, communication between groups
                > doesn't happen as often as it should, and is generally filtered
                > through the development manager.
                >


                Because off-the-shelf agile development makes heavy use of in-person and
                tacit communication. distributed agile development will require various
                compensations and compromises. When you say your group is agile but
                distributed, how do you plan for that to work?

                William
              • Alice Preston
                Cherie, you might want to see the article Becoming Agile: Usability and Short Project Cycles by Gwen Pearson and Susan Pearsall. It s in the latest issue of
                Message 7 of 15 , Nov 29, 2005
                • 0 Attachment
                  Cherie, you might want to see the article "Becoming Agile: Usability and
                  Short Project Cycles" by Gwen Pearson and Susan Pearsall. It's in the latest
                  issue of the UPA magazine, User Experience, which is arriving soon at a
                  mailbox near you (assuming you're a UPA member). They present a sanitized
                  version of the documentation method they've evolved with their team (unlike
                  yours, their team is co-located).

                  Disclosure: I'm the associate managing editor for the magazine.

                  Alice Preston
                  Princeton, NJ
                • Jeff Patton
                  ... challenge we face in this company is that our development group is in Hungary.
                  Message 8 of 15 , Nov 29, 2005
                  • 0 Attachment
                    --- In agile-usability@yahoogroups.com, Cherie Hinson
                    <hinson_heyer@y...> wrote:
                    >
                    > To add an additional twist to my original posting, the
                    challenge we face in this company is that our development group is in
                    Hungary. <

                    For better or worse, many in the agile community consider this
                    a "doctor it hurts when I do this" issue - to which Groucho Marx
                    responds "Don't do that." That's not helpful advice in your
                    situation I understand.

                    I just did a quick web search for the original Groucho quote, and
                    found this one too - it might be more appropriate:

                    "Doctor, I've broken my arm in several places."
                    Doctor: "Then don't go to those places."

                    At ThoughtWorks we do a fair bit of distributed development in an
                    agile style. To try to keep it agile, we keep whole teams on each
                    side of the ocean - developers on each side, business analysts on
                    each side. We tend to fly people back and forth a lot so people in
                    India [in our case] get experience working with their teamates in the
                    US and vice versa - yes we ship US people to India as well. That's a
                    big commitment to agile development. But, it allows our
                    conversations over the phone to be frequent and rich - although
                    they're at awkward times.

                    If face to face communication isn't an option for you, then you've
                    sorta got a break in your agile chain - at least that part of your
                    agile methodology isn't very agile. I'd hope your manger understands
                    that. You've got to compensate by doing more work. That might mean
                    you're writing a very long document to describe how the user
                    interface should look at behave to spoon feed it overseas. It's
                    about that time, after spending lots of $$ for you to write
                    docuemnts, that a sensible manager might say: "Why doesn't the
                    offshore team work on business functionality and we'll define the API
                    to talk to it. We'll build a small team over here to create user
                    interface." Breaking the architecture into two teams - one
                    responsible for UI, the other for raw functionality has work for
                    organizations like flickr.com.

                    thanks,

                    -Jeff
                  • Dave Churchville
                    ... Tough problem. I ve had a similar situation in the past, where we needed overall specs to comply with regulatory requirements, but really only wanted
                    Message 9 of 15 , Nov 30, 2005
                    • 0 Attachment
                      --- In agile-usability@yahoogroups.com, "hinson_heyer"
                      <hinson_heyer@y...> wrote:

                      > Recently, however, the software engineering manager has started to
                      > complain that our specs are too big, and it's too hard for the
                      > programmers to follow what they need to build for a particular
                      > iteration. He would prefer "delta" specs for each iteration that
                      > only contain what is changing for that functionality in that
                      > particular iteration. My concern is that if we only document
                      > initially what we determine can be built in an iteration we will
                      > lose the big picture of what we want the interaction to be.
                      >
                      > So I'm wondering what best practices exist for documenting the UI in
                      > an agile environment?

                      Tough problem. I've had a similar situation in the past, where we
                      needed "overall" specs to comply with regulatory requirements, but
                      really only wanted incremental specs for ongoing work.

                      So the dilemma was to either duplicate the work, or try to get by with
                      only incremental specs. I can tell you that from the development
                      perspective, incremental specs are great, but only if there is a
                      comprehensive set of acceptance tests (automated or otherwise) that
                      will catch any changes in other behavior (not meant to change).

                      The best solution we found was to create an incremental spec FIRST,
                      with the additions, deletions and changes, so that it was very clear
                      to both the development and testing teams what was actually changing
                      for the release or iteration.

                      This meant a little extra work in backfilling this incremental
                      document into the main "master spec", but the benefit was that we
                      still got to have a "big picture" spec for new team memebers,
                      regulatory tracking, etc., without having to actually use that as the
                      source for specifications during an iteration.

                      It doesn't feel very agile to have big spec documents that need
                      constant updating for every change, but in some organizations, there
                      isn't much choice (that was true for me - FDA regulated).

                      So to be more agile strategically, you might need to be a little less
                      agile tactically (how's that for a paradox?)

                      --Dave

                      -----------------------------------------------
                      Dave Churchville
                      http://www.extremeplanner.com
                      Agile Project Management for Distributed Teams
                      -----------------------------------------------
                    • Ron Vutpakdi
                      ... As an aside, I ve recently started using a trial version of SketchBook Pro on a borrowed TabletPC for my initial interaction design sketching. Lovely
                      Message 10 of 15 , Nov 30, 2005
                      • 0 Attachment
                        --- In agile-usability@yahoogroups.com, "Jeff Patton" <jpatton@a...>
                        wrote:
                        >
                        > In an ideal Agile world you might draw something on a white board,
                        > make big hand gestures, then shoot a digital photograph of it for
                        > posterity. In practice today I do paper prototyping with old
                        > fashioned pencil and paper, then photocopy the prototype in various
                        > stages of workflow to construct a storyboard on poster paper -
                        > annotated with interaction details.

                        As an aside, I've recently started using a trial version of SketchBook
                        Pro on a borrowed TabletPC for my initial interaction design
                        sketching. Lovely tool, perfect for that initial sketch work and for
                        quick markups of existing interfaces. I'm limited to the original
                        version of SketchBook Pro (borrowed TabletPC so can't install the
                        latest, haven't been able to order a TabletPC of my own yet), so I
                        haven't been able to use SketchBook Pro to its fullest capabilities,
                        but it's already been a big help.

                        I'm eventually planning on doing of what you do (and I did) both on
                        paper (using some printed versions of sketches) and electronically (so
                        that I can easily distribute). The electronic versions will be PDFs
                        created using the "sketches" assembled in Canvas (my main post "pen &
                        paper" design tool).

                        >
                        > The real point here is that no document, no matter how well written
                        > can replace face to face collaboration.


                        Definitely. I'm running into communication difficulties also right
                        now since I've started working with a team in Aberdeen (with only a 6
                        hr time shift). Still pushing for face to face meetings with the
                        developers. :-P

                        Ron

                        PS: No, I don't work for Alias, and, no, Lynn hasn't slipped me a
                        bribe. ;-)
                      • Jade Ohlhauser
                        We ve moved all documentation to a single wiki. And I mean everything: functional specs, technical specs, testing lists, training, user reference & help, wish
                        Message 11 of 15 , Nov 30, 2005
                        • 0 Attachment
                          We've moved all documentation to a single wiki. And I mean everything: functional specs, technical specs, testing lists, training, user reference & help, wish lists, development procedures, HIG, and more. We moved to this from a miasma of word docs and other files scattered across network folders and code vaults. Having been using this "new way" for several months now, everyone involved agrees this is a total improvement in every way.
                           
                          Main benefits over traditional documentation
                          - Linking among documents
                          - Flexible organization
                          - One search
                          - No overhead for formatting, cover pages, etc.
                          - Change history
                           
                          How this relates to you
                          - The wiki pages are the complete spec, but anyone can quickly bring up a visual difference to see what's changed. We do an additional summary of changes as tasks in our defect tracker/source control.
                           
                          Having been freed from file management and document formatting, our development team now produces far more documentation than they did before. In the "old days" getting people to document was like pulling teeth. Now it's the opposite (I guess that would be pushing teeth?). 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.
                           
                          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 Dave Churchville
                          Sent: Wednesday, November 30, 2005 9:18 AM
                          To: agile-usability@yahoogroups.com
                          Subject: [agile-usability] Re: documenting the UI in an agile environment

                          --- In agile-usability@yahoogroups.com, "hinson_heyer"
                          <hinson_heyer@y...> wrote:

                          > Recently,
                          however, the software engineering manager has started to
                          > complain that
                          our specs are too big, and it's too hard for the
                          > programmers to follow
                          what they need to build for a particular
                          > iteration.  He would
                          prefer "delta" specs for each iteration that
                          > only contain what is
                          changing for that functionality in that
                          > particular iteration.  My
                          concern is that if we only document
                          > initially what we determine can be
                          built in an iteration we will
                          > lose the big picture of what we want the
                          interaction to be.
                          >
                          > So I'm wondering what best practices exist
                          for documenting the UI in
                          > an agile environment?

                          Tough problem.  I've had a similar situation in the past, where we
                          needed "overall" specs to comply with regulatory requirements, but
                          really only wanted incremental specs for ongoing work.

                          So the dilemma was to either duplicate the work, or try to get by with
                          only incremental specs.  I can tell you that from the development
                          perspective, incremental specs are great, but only if there is a
                          comprehensive set of acceptance tests (automated or otherwise) that
                          will catch any changes in other behavior (not meant to change).

                          The best solution we found was to create an incremental spec FIRST,
                          with the additions, deletions and changes, so that it was very clear
                          to both the development and testing teams what was actually changing
                          for the release or iteration.

                          This meant a little extra work in backfilling this incremental
                          document into the main "master spec", but the benefit was that we
                          still got to have a "big picture" spec for new team memebers,
                          regulatory tracking, etc., without having to actually use that as the
                          source for specifications during an iteration.

                          It doesn't feel very agile to have big spec documents that need
                          constant updating for every change, but in some organizations, there
                          isn't much choice (that was true for me - FDA regulated). 

                          So to be more agile strategically, you might need to be a little less
                          agile tactically (how's that for a paradox?)

                          --Dave

                          -----------------------------------------------
                          Dave Churchville
                          http://www.extremeplanner.com
                          Agile Project Management for Distributed Teams
                          -----------------------------------------------



                        • 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 12 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 13 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 14 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 15 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.