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

Re: How Tech Authors Fit into the Agile Team

Expand Messages
  • 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 1 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 2 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 3 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 4 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 5 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 6 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 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...

                  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 8 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 9 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 10 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.