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

Re: [agile-usability] How Tech Authors Fit into the Agile Team

Expand Messages
  • Lynn Miller
    I m not a TA but I work very closely with the ones at my company. I guess my first question would have to be: Do you have anyone doing usability at your
    Message 1 of 12 , Jun 28, 2005
    • 0 Attachment
      I'm not a TA but I work very closely with the ones at my company.

      I guess my first question would have to be: Do you have anyone doing
      usability at your company?

      In my company the TA works with the usability group. They attend design
      meetings with us so that they can get a good understanding of what we
      are trying to achieve, and can write the chm files before the code is
      written. We then include the docs when we do low-fidelity usability
      testing of the design. This works out really well. If the user goes to
      the docs for help, we discover the terminology that the user is looking
      for, how well the entry points work, and if the actual text is
      understandable.

      So basically the docs are prototyped and iterated at the same time the
      design is. By the time we have a final design to give to the developers,
      the TA also has the final text of the documentation. (The images have
      to wait until the implementation is complete.)

      As for the "UI gaffs", we solved this problem by having acceptance
      criteria for each feature. We use "Feature cards" that track what is
      going in for each cycle. The front of the feature card says what the
      feature is, who the developer is, what the time estimate is, etc. On the
      back of the card, the usability group writes down the acceptance
      criteria which specifies what a 'complete' feature is. And a complete
      and acceptable UI is part of the acceptance criteria. (We don't just say
      "a complete and acceptable UI". We list the specifics to achieve that
      for the feature in question.)

      I hope this helps.

      Lynn

      rogersnee2003 wrote:
      > Hi Folks,
      >
      > I work as a Technical Author in a small software company in a
      > northern city in the U.K.
      >
      > We have migrated to an Agile/ XP environment,with a two-week
      > iteration cycle.
      >
      > Our products have HTML Help chm files, pdf user guides-tutorials-
      > quick tours, and in some instances , training videos, all of which I
      > produce.
      >
      > User Stories are on cards with corresponding cards for
      > doc/video/graphic changes/additions, everything derived from the
      > Review-Planning meeting for the upcoming iteration.
      >
      > The daily SCRUM stand-ups are focussed on the card movements, and
      > the team operate pretty proactively. In some cases, the changes in
      > feature set - function don't appear for several daily program
      > builds, and then pile up in the daily builds towards the end of the
      > two week iteration.
      >
      > The aim is to be able to produce releasable product every two
      > weeks. Actual release periods are approx. 3 months.
      >
      > As the TA, I have to start the feature doc/help/video well before it
      > actually starts to appear in the daily builds. Placeholders fill
      > the gap until the UI is sorted. For videos however, you do need a
      > functioning feature set to record footage. Inevitably, this is now
      > pushing the envelope at the end of the iteration.
      >
      > My question(s) to the group are:
      >
      > 1) How do other Tech Authors in other Agile Teams adapt to this
      > environment?
      >
      > 2) As the features appear, I do a lot of exploratory testing using
      > tests that I helped to write before the feature work is
      > started. There is a lot of poor legacy code buried on the "shop
      > floor", and since I'm on the receiving end, I'm getting a little
      > worried that the quality of the product being produced under our
      > agile environment, is not as good as the old waterfall
      > environment.
      >
      > Class 1A bugs get fixed immediately. However, UI gaffs that the
      > user sees right up front get relegated to a pile for the product
      > owner to prioritise in the next iteration planning meet.
      >
      > The question to the group is - poor legacy code is not unique to
      > us. Does any of the above, ring a bell with anyone in the group?
      >
      > Sorry to have rambled on so long.
      >
      > Thanks for reading this far.
      >
      > Roger Snee
      >
      > Somewhere in the northern jungles of the U.K.
      >
      >
    • Sue Heim
      Lynn replied to this question a while ago... I still have a question. How have any of you who are working under the Agile methodology integrating user
      Message 2 of 12 , Aug 1, 2005
      • 0 Attachment
        Lynn replied to this question a while ago... I still have a question.
        How have any of you who are working under the Agile methodology
        integrating user documentation into your process? Or, as some seem to
        believe, the goal in Agile development is to completely "do away
        with" all user documentation? (And yes, I'm an online help author, so
        I'll fight you tooth and nail on that one! <grin>)

        Thanks for any insight you may have,
        ...sue

        --- In agile-usability@yahoogroups.com, Lynn Miller <lmiller@a...>
        wrote:
        > I'm not a TA but I work very closely with the ones at my company.
        >
        > I guess my first question would have to be: Do you have anyone
        doing
        > usability at your company?
        >
        > In my company the TA works with the usability group. They attend
        design
        > meetings with us so that they can get a good understanding of what
        we
        > are trying to achieve, and can write the chm files before the code
        is
        > written. We then include the docs when we do low-fidelity
        usability
        > testing of the design. This works out really well. If the user
        goes to
        > the docs for help, we discover the terminology that the user is
        looking
        > for, how well the entry points work, and if the actual text is
        > understandable.
        >
        > So basically the docs are prototyped and iterated at the same time
        the
        > design is. By the time we have a final design to give to the
        developers,
        > the TA also has the final text of the documentation. (The images
        have
        > to wait until the implementation is complete.)
        >
        > As for the "UI gaffs", we solved this problem by having acceptance
        > criteria for each feature. We use "Feature cards" that track what
        is
        > going in for each cycle. The front of the feature card says what
        the
        > feature is, who the developer is, what the time estimate is, etc.
        On the
        > back of the card, the usability group writes down the acceptance
        > criteria which specifies what a 'complete' feature is. And a
        complete
        > and acceptable UI is part of the acceptance criteria. (We don't
        just say
        > "a complete and acceptable UI". We list the specifics to achieve
        that
        > for the feature in question.)
        >
        > I hope this helps.
      • Ron Jeffries
        ... As far as I know, there is no movement or subthread in Agile to do away with user docs, or any docs that are needed. Here are a few articles regarding
        Message 3 of 12 , Aug 1, 2005
        • 0 Attachment
          On Monday, August 1, 2005, at 2:41:06 PM, Sue Heim wrote:

          > Lynn replied to this question a while ago... I still have a question.
          > How have any of you who are working under the Agile methodology
          > integrating user documentation into your process? Or, as some seem to
          > believe, the goal in Agile development is to completely "do away
          > with" all user documentation? (And yes, I'm an online help author, so
          > I'll fight you tooth and nail on that one! <grin>)

          As far as I know, there is no movement or subthread in Agile to do
          away with user docs, or any docs that are needed.

          Here are a few articles regarding documentation and Extreme
          Programming ...

          http://www.xprogramming.com/xpmag/manualsInXp.htm
          http://www.xprogramming.com/xpmag/Ferlazzo.htm
          http://www.xprogramming.com/xpmag/FussAboutDocumentation.htm
          http://www.xprogramming.com/xpmag/expDocumentationInXp.htm
          http://www.xprogramming.com/xpmag/natural.htm

          Ron Jeffries
          www.XProgramming.com
          It's easy to have a complicated idea. It's very very hard to have a simple idea.
          -- Carver Mead
        • Sue Heim
          Ron, thanks so much for these links! There s a help authoring list that has been all up in arms lately... one member mentioned that his company (who has
          Message 4 of 12 , Aug 2, 2005
          • 0 Attachment
            Ron, thanks so much for these links! There's a help authoring list that has
            been all up in arms lately... one member mentioned that his company (who has
            embraced the Agile development paradigm) is completely doing away with all
            their docs. And, naturally, all the writers are a bit negative about that
            concept. I knew that the elimination of docs was not a goal -- or even a
            sub-goal -- of products created within the Agile world.

            ...sue

            Ron Jeffries:
            >As far as I know, there is no movement or subthread in Agile to do
            >away with user docs, or any docs that are needed.
            >
            >Here are a few articles regarding documentation and Extreme
            >Programming ...
            >
            >http://www.xprogramming.com/xpmag/manualsInXp.htm
            >http://www.xprogramming.com/xpmag/Ferlazzo.htm
            >http://www.xprogramming.com/xpmag/FussAboutDocumentation.htm
            >http://www.xprogramming.com/xpmag/expDocumentationInXp.htm
            >http://www.xprogramming.com/xpmag/natural.htm
          • Lynn Miller
            ... Part of the agile process is to significantly reduce the amount of internal documentation required (requirements docs, design specs, status reports, that
            Message 5 of 12 , Aug 2, 2005
            • 0 Attachment
              Sue Heim wrote:
              > Ron, thanks so much for these links! There's a help authoring list that has
              > been all up in arms lately... one member mentioned that his company (who has
              > embraced the Agile development paradigm) is completely doing away with all
              > their docs.

              Part of the agile process is to significantly reduce the amount of
              internal documentation required (requirements docs, design specs, status
              reports, that kind of stuff) but not external (user) documentation.

              Lynn
            • William Pietri
              ... I d strongly agree with that. I ve only noticed two big differences on my projects. The obvious one is that the docs are done incrementally and in a way
              Message 6 of 12 , Aug 3, 2005
              • 0 Attachment
                On Tue, 2005-08-02 at 09:25 -0400, Lynn Miller wrote:
                > Sue Heim wrote:
                > > Ron, thanks so much for these links! There's a help authoring list that has
                > > been all up in arms lately... one member mentioned that his company (who has
                > > embraced the Agile development paradigm) is completely doing away with all
                > > their docs.
                >
                > Part of the agile process is to significantly reduce the amount of
                > internal documentation required (requirements docs, design specs, status
                > reports, that kind of stuff) but not external (user) documentation.

                I'd strongly agree with that.

                I've only noticed two big differences on my projects. The obvious one is
                that the docs are done incrementally and in a way more integrated with
                development. One project I'm on just did a release to a handful of hardy
                alpha testers before writing most of the "getting started"
                documentation. By walking each person through by hand, they got to see
                where people got stuck and what questions they had. This also yielded a
                series of minor application tweaks: better to fix the problem then to
                document it.

                The more subtle one is that developers are more inclined to make tools
                to make documentation editing easy. On another project, marketing was
                making a lot of text changes as they got user feedback. So that
                developers didn't have to be involved in every single change, the
                product manager spent a couple of points on a simple content management
                system.

                William


                --
                William Pietri <william@...>
              • Adrian Howard
                ... [snip] As you ve probably already realised nobody in the agile world wants to do away with user documentation :-) Well, apart from the fact that we try and
                Message 7 of 12 , Aug 4, 2005
                • 0 Attachment
                  On 1 Aug 2005, at 19:41, Sue Heim wrote:
                  > Lynn replied to this question a while ago... I still have a question.
                  > How have any of you who are working under the Agile methodology
                  > integrating user documentation into your process? Or, as some seem to
                  > believe, the goal in Agile development is to completely "do away
                  > with" all user documentation? (And yes, I'm an online help author, so
                  > I'll fight you tooth and nail on that one! <grin>)
                  [snip]

                  As you've probably already realised nobody in the agile world wants
                  to do away with user documentation :-)

                  Well, apart from the fact that we try and build better software than
                  meets the user's expectations, hopefully making the user
                  documentation less weighty and easier to write.

                  I've not worked on an agile team that had a dedicated technical
                  author, but if I got the opportunity this is what I'd try and do:

                  * I'd like the TA working in the same room as everybody else

                  * I'd involve the TA in the planning game. In my experience good
                  TAs are skilled in getting into the mindset of users, and can perform
                  some of the roles that somebody with UCD skills performs. Rather than
                  spending a lot of effort writing documentation that makes an
                  unintuitive piece of software look simple, they can help make the
                  software simple and easier to document.

                  * For much the same reason I'd involve the TA in producing
                  customer tests.

                  * I'd like the TA to coach and pair with the developers some of
                  the time, so they can become more aware of how the code affects the
                  user documentation (and vice versa) and discover ways they can help
                  each other.

                  * I'd want the release cycle of the user documentation to be
                  synchronised with the release cycle of the software.

                  Hope this helps.

                  Adrian
                • desireesy
                  ... Sue, just to add a couple of points to what Lynn said earlier: - If you ve got a usability group, working agile is pretty rewarding because you will see
                  Message 8 of 12 , Aug 4, 2005
                  • 0 Attachment
                    > On 1 Aug 2005, at 19:41, Sue Heim wrote:
                    > > Lynn replied to this question a while ago...

                    Sue, just to add a couple of points to what Lynn said earlier:

                    - If you've got a usability group, working agile is pretty rewarding
                    because you will see incremental improvements to your docs, but it
                    definitely requires that you be willing to re-write, and in some cases
                    completely restructure. Consider iteration the coin in trade for the
                    reward of seeing users find and use your information.

                    - One trick that lets you test structure of docs before you may have
                    content finished is to create a CHM/Help framework with just headings
                    and index entries. The topics themselves are "To be written." Then
                    you can query on what sort of help users expected to see (e.g.,
                    procedural -- for which problem? reference -- of what term? etc.)

                    - Depending on how easy your set-up is to populate the Help file, you
                    can either drop in topics as you write them, or just print the topics
                    individually and hand them to users when they get to the topic. If
                    you have conceptual illustrations, you can also do low-fidelity tests
                    with hand-drawn sketches.

                    - Keep enriching the index with user synonyms as you test.

                    Another nice thing about working agile is that despite the re-writing,
                    it's much easier to finish docs incrementally than having to wait
                    until the last couple of months for all the pieces to snap into place
                    so you can write about full workflows and know you're right.

                    Desiree
                  • Baker, Lisa
                    We ve been doing XP/agile for about 3 years. We dumped marketing requirement documents and product requirement documents right away. High level design
                    Message 9 of 12 , Aug 4, 2005
                    • 0 Attachment
                      We've been doing XP/agile for about 3 years. We dumped marketing
                      requirement documents and product requirement documents right away. High
                      level design documents were also early casualties, but our loyal/big
                      customers and customer support has been asking for them so they have
                      made a resurgence in the last 6-8 months.
                      Our user docs are as thick or thin as they ever were. An extra
                      challenge for the doc team is that we localize the product into 8
                      languages, so doing the documentation iteratively as the stories
                      complete and dropping to localization iteratively adds some management
                      headache.
                      Typically, the doc team starts the writing during the iteration, but
                      have tired of documenting the same thing 2 or 3 times when the prototype
                      -> implementation changes due to customer and marketing feedback. When
                      possible, it seems like they are backing off a little more and waiting
                      for a story to actually pass acceptance tests before they put a lot of
                      elbow grease and brain cells into a particular section.
                      Lisa


                      Lisa Baker
                      Human Factors Lead
                      LANDesk Software, Inc.
                      Lisa.baker@...
                      801.208.1315

                      "Simplifying our customers' work"

                      This email, and any files previous email messages included with it, may contain confidential and/or privileged material. If you are not the intended recipient please contact the sender and delete all copies.
                    • Sue Heim (Home)
                      Desiree wrote: ... I actually do this now anyways. I do it partly for people to see and evaluate the structure, and partly so that *I* know what the
                      Message 10 of 12 , Aug 4, 2005
                      • 0 Attachment
                        Desiree wrote:
                        <snip>
                        > - One trick that lets you test structure of docs before you may have
                        > content finished is to create a CHM/Help framework with just headings
                        > and index entries. The topics themselves are "To be written." Then
                        > you can query on what sort of help users expected to see (e.g.,
                        > procedural -- for which problem? reference -- of what term? etc.)

                        I actually do this now anyways. I do it partly for people to see and
                        evaluate the structure, and partly so that *I* know what the heck it is that
                        I'm doing, and supposed to be doing.

                        > - Depending on how easy your set-up is to populate the Help file, you
                        > can either drop in topics as you write them, or just print the topics
                        > individually and hand them to users when they get to the topic. If
                        > you have conceptual illustrations, you can also do low-fidelity tests
                        > with hand-drawn sketches.

                        I use AuthorIT as my help authoring tool, and this process works well within
                        that tool. I also have release states that I can set, so that I can easily
                        mark topics that are ready to review, have been reviewed, need more info
                        from an SME, need to be tested, and so on.

                        > - Keep enriching the index with user synonyms as you test.

                        Actually, this is a good point and one that many writers forget about. I'm a
                        bit of a goddess when it comes to indexing, and I always ALWAYS index as I
                        go. But many writers hate to index, save it for last, and blast thru
                        something really quickly just to get it done. The advantage of working
                        closely within a team is you get to hear and see how components are
                        referenced, and can easily pick up those synonyms and add 'em to the index.

                        > Another nice thing about working agile is that despite the re-writing,
                        > it's much easier to finish docs incrementally than having to wait
                        > until the last couple of months for all the pieces to snap into place
                        > so you can write about full workflows and know you're right.

                        We were starting to implement a bastardized version of Agile where I used to
                        work at. The problem was that it was almost impossible to do an incremental
                        build that was "set" because things continued to change. I guess, now that I
                        think of it, there was less process than there should've been. As in, well,
                        OK, *no* process!!!!!

                        ...sue
                      • Sue Heim (Home)
                        Thank you, all of you, for your great comments about how us writers fit into the Agile team. I think we ve finally got the writers calmed down. They were all
                        Message 11 of 12 , Aug 4, 2005
                        • 0 Attachment
                          Thank you, all of you, for your great comments about how us writers fit into
                          the Agile team. I think we've finally got the writers calmed down. They were
                          all freaked out because one company implemented Agile and tossed all user
                          docs, and so there was lots of hullaballo for naught.

                          Anyways, thanks for your comments, insight, and wonderful suggestions!

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