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

How Tech Authors Fit into the Agile Team

Expand Messages
  • rogersnee2003
    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
    Message 1 of 12 , May 8, 2005
      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.
    • 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 2 of 12 , Jun 28, 2005
        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 3 of 12 , Aug 1 11:41 AM
          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 4 of 12 , Aug 1 8:06 PM
            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 5 of 12 , Aug 2 6:19 AM
              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 6 of 12 , Aug 2 6:25 AM
                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 7 of 12 , Aug 3 9:49 AM
                  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 8 of 12 , Aug 4 10:59 AM
                    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 9 of 12 , Aug 4 2:54 PM
                      > 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 10 of 12 , Aug 4 5:17 PM
                        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 11 of 12 , Aug 4 7:42 PM
                          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 12 of 12 , Aug 4 7:43 PM
                            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.