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

Re: [XP] Purpose Driven Development - starting at the end

Expand Messages
  • Steven Gordon
    I would like to read your little contribution , but I just cannot read 500+ words not broken down into paragraphs. ... [Non-text portions of this message have
    Message 1 of 41 , Jan 23, 2012
      I would like to read your "little contribution", but I just cannot read
      500+ words not broken down into paragraphs.

      On Mon, Jan 23, 2012 at 3:25 PM, M. Manca <m.manca@...>wrote:

      > **
      > Il 23/01/2012 21:40, jacek_ratzinger ha scritto:
      > >
      > >
      > > Could we use frameworks such as Concordion (http://www.concordion.org)
      > > to make our acceptance tests readable to non technical people?
      > > Could this lead us to user manuals that are executable?
      > >
      > I would try to give my little contribute. I develop embedded systems so
      > I develop embedded firmware/software. More then 20 years ago I worked in
      > an Italian plant of a Swiss based company. I wrote applications starting
      > with very well written specification documents that generally I received
      > by my R&D manager. I were 50% of the team, the mechanics team were about
      > 12 engineers, we didn't work collaborating, we were 2 separate teams and
      > we talk about the project during weekly meetings (2-4 hours every week
      > at beginning). Generally requirements were well written but about 50% of
      > them were really not useful at all because they were already known and
      > the other 50% net to talk about. The same team also designed the
      > electronics. We made pair programming because.... we had only 1 IBM
      > PC... and we learn to simulate the system behaviour simply because we
      > wrote the application months before to have a prototype system; we wrote
      > and executed tests similar to unit tests but about 50% of them manually
      > executed. We made acceptance test after the prototype system was ready.
      > We had so much free time that also we wrote user's and service's
      > manuals. We really had a low error rate, 2 or 3 severe bugs normally
      > discovered during prototyping and more or less 10-20 minor bugs.
      > Generally we discovered that some mechanics part didn't work as expected
      > and so we rewrote some modules. Ah... don't forget... this applications
      > were written in assembly. So after some months we had a prototype to
      > test our application but we had our user's manual, service's manual,
      > installation's manual ready and well done and all the R&D team used them
      > :-). The manager presented the machine to our marketing and technical
      > service engineers that inevitably found a lot of things not well done
      > (they really were the only engineers to understand customers needs).
      > This means a lot of manuals to rewrite, tests to repeat and so on;
      > practically the application worked as designed but the design
      > requirements were very poor and the machine difficult to use and
      > difficult to understand what it was performing. We were lucky: due to a
      > market crisis some managers left the company (also a lot of engineers)
      > and the new CEO redesign the organization in a way that today we could
      > call agile. The R&D team was redesigned, we were only 1 project team:
      > electronics, software, mechanics engineers, service engineers, marketing
      > people and quality department engineers worked without a rigid
      > requirement document for about 9 months but collecting customers'
      > requirements and observations, an invaluable set of informations that we
      > used to redesign completely the machine. After we had a 2 month beta
      > testing on some customers sites and we went on production without any
      > bug or relevant problem. To test the machine we used written examples
      > that we traduced manually so I can say that they were executable
      > examples. We made also a lot of prototyping at system level with little
      > engineers team (not more then 3 engineers) with a team life of 15-20
      > days just to solve a specific problem or to find a specific solution.
      > Our Swiss managers really think at this organization as an universal
      > chaos but in 9 months we redesigned completely the machine that was
      > initially designed in 16 months. During beta testing we also wrote
      > product's manual, service's manual, user's manual and also I had the
      > time to organize and teach to the service tech course for our world
      > field service engineers. At the end we had a big party to celebrate this
      > "strange" success and we had another one to celebrate the 1000th machine
      > sold. Until end of life the company sold about 7500 machines, about 5
      > times more then the best marketing prediction.
      > >
      > >
      > > Greets, Jacek
      > >
      > > --- In extremeprogramming@yahoogroups.com
      > > <mailto:extremeprogramming%40yahoogroups.com>, RonJeffries
      > > <ronjeffries@...> wrote:
      > > >
      > > >
      > > > On Jan 23, 2012, at 3:28 PM, jacek_ratzinger wrote:
      > > >
      > > > > Are tests the input for documenation or is documentation the input
      > > for tests:
      > > > > tests => documentation ?
      > > > > documentation => tests ?
      > > >
      > > > Conversation => Design, Documentation, Tests
      > > > >
      > > > > What about an "executable documentation"?
      > > > > tests = documentation
      > > > > documentation = tests :-)
      > > >
      > > >
      > > > Tests are executable documentation. User manuals generally are not.
      > > >
      > > > Ron Jeffries
      > > > www.XProgramming.com
      > > > If it is more than you need, it is waste. -- Andy Seidl
      > > >
      > > >
      > > >
      > > > [Non-text portions of this message have been removed]
      > > >
      > >
      > >
      > [Non-text portions of this message have been removed]

      [Non-text portions of this message have been removed]
    • Charlie Poole
      Hi Jacek, On Fri, Jan 27, 2012 at 12:30 AM, jacek_ratzinger wrote: ... One must always worry about meaning of terms
      Message 41 of 41 , Jan 27, 2012
        Hi Jacek,

        On Fri, Jan 27, 2012 at 12:30 AM, jacek_ratzinger
        <ratzinger.jacek@...> wrote:
        > Perhaps "user documentation" has negative connotations such as the term "specification" for Charlie Poole (http://tech.groups.yahoo.com/group/testdrivendevelopment/message/34964).
        > What is a better term for the information you would like to find, when you are looking for a new application?

        One must always worry about meaning of terms as it is perceived by the
        audience. In our field, meanings
        can change every five years or so, so much of your audience already
        has established meanings for
        terms if you re-use a term from "old times" in a new way.

        This is made more difficult by the fact that things change at
        different rates in different places - i.e.
        different countries, different companies, different teams - so usage
        is not always common.

        In the 80s (I could go back further, but why bother) a "specification"
        was clearly something very
        finished, very formal and very unchangeable - at least not changed
        without going through a
        very large formal process. But "in the 80s" is not quite correct, as
        there are companies using
        "specifications" in this way right now.

        Similarly, a "user manual" (not quite the same as "user
        documentation") was similar to a
        specification, but more oriented to those things a user would see. The
        technique of writing
        the user manual first was put out (for the first time AFAIK) in that
        same decade. The idea
        (back then) was to create a very finished document, complete with
        illustrations, so that
        programmers could work toward software that matched the manual.

        In the late 90s, I spent some time in a group at Microsoft and saw
        "specifications" that were
        very much like user manuals. That is, artists worked carefully to
        create the desired appearance
        and writers specified the exact steps that users should follow when
        using the app. These
        specs were sometimes changed, but not lightly. I guess part of the
        reason was that a lot
        of effort went into producing them.

        In all those past examples, what I see operating is a desire to make
        it *unnecessary* for
        the programmer to give much thought to the purpose of the application.
        Specs were
        written by analysts or program managers. Manuals were created by
        artists and technical
        writers. Programmers just programmed.

        Of course, I see that is not what you are trying to do. You don't want
        to diminish the
        understanding of the programmers but to increase it. But if you use
        terms that have
        been associated with the "dumbing down" of the programmer's craft in
        the past, you
        shouldn't be surprised if at least some folks make that association.

        I think "purpose" is a good term. I've seen too many teams who do NOT understand
        the purpose of what they do. For example, I've seen teams with very
        poor understanding
        of how the company they work in makes its money. Naturally, such
        programmers need
        to be given very precise instructions (e.g. a manual) because they
        don't have the
        background to make intelligent decisions. It seems obvious to me, however, that
        the better course is to educate them in the real purpose of what they
        are doing and
        how it will be used. A "user manual" - at least as the term is
        normally used - would
        only scratch the surface of such ignorance.

        For me, it's not so much that terms have a _*negative* connotation as that they
        may have an association that runs contrary to your overall aims.

        How about "user story"? Do you have some association with that term that makes
        you prefer "user manual"?

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