Re: Agile, SCRUM and Technical Writing

Subject: Re: Agile, SCRUM and Technical Writing
From: Ned Bedinger <doc -at- edwordsmith -dot- com>
To: Gene Kim-Eng <techwr -at- genek -dot- com>
Date: Sat, 17 Feb 2007 12:31:49 -0800

Gene Kim-Eng wrote:

----- Original Message ----- From: "Ned Bedinger" <doc -at- edwordsmith -dot- com>

After the project is judged a success or not, and after you've decided if it had a good team and insight or not, then you could try to use the results to explain what was happening, even if the sample turned out to be all not-good teams having not-good insight.

I have never seen what I thought was a "good team" with "good insight"
that did not at least *try* to write down what the product they were
starting to develop was supposed to do, and have seen no successful
products that came out of teams with "poor" insight.

Agreed. When I need to gather impressions and details of the requirements and design information, I naturally hope that something is written down somewhere. If it is, my job costs the company much less. If it isn't, I warm up the crawler, because I know that the project is going to be a rocky one for me, with a lot of cooked target dates, and a lot of intervals spent doodling on my notes while a developer tests their comprehension upon a white board. Incidently, this is why I love printing whiteboards.


My manager in an IT writing group once put me on the end of a software development project. I spent a couple of days interviewing a developer and writing up the work. The day after I circulated it for review, that developer was gone. Apparently, said developer's grasp of the project was not virtuous (it verged on incompetence), and no one even realized it until the written version made it manifest.
I think a lot more axes would fall if the truths about some projects ever were to be written down.



Another after-the-fact document is the specification that gets written after product development is completed. A dev manager once candidly explained these to me: How could they possibly know what the specification of the final product is, unless the product is already finished?

There is a difference between a development spec that describes
to your team what they are trying to do (eyes on the prize and all
that) and a product spec that describes to your prospective buyers
what the finished effort looks like.


True, still I am talking about after-the-fact specs of the internal variety--IOW, the documentation of the dev team project, not just the finished product. When done this way, the proj docs yield only a small fraction of the value, in terms of capability and maturity information, that honest project documentation could reveal. I think management tends to *want* to believe that software development "learning" is a problem only for development team members. I'm not sure why this would be true, but suspect it is a symptom of denial -- managers without strong technical backgrounds usually doesn't want to acknowledge the significance of the wide gulf of technical knowledge that separates them from the engineers. Speaking as the tech writer who uses all available resources to understand a project, a company that permits development to proceed this way has memory-management problems--not only do they never gain self-knowledge about their development capability and maturity, but they also end up with a bazillion lines of code that they've paid for but know *nothing* about.


I think that if you boiled down all of the variations on this theme, you'd end up with the idea that they're working on an evolving prototype that will change (and probably a lot). I also suspect that this is another way of saying 'good team but no insight.'

Rigidly hewing to your original requirements without making the
occaisional adjustment to allow for things you discover were just
a bit too ambitious,


Protoyping, as THE major dev methodogy, is something more haphazard and extreme than navigating around the occasional obstacle. It would be like bird-dogging across the countryside in search of the destination, instead of getting directions. I think prototyping is more fun that getting serious about how to best do something, and that is why it appears as often as it does, as a major dev methodology.


or to changes that occur in your target market
as your work progresses is probably almost as bad a mistake as
jumping feet first into a project without some sort of roadmap
that says where you're trying to go. I would expect a good project's requirements documents to have been revised numerous times along the way to product completion, but with review and buy-in from the various stakeholders,

As you say, change is to be expected. The tree that won't bend will snap when the wind blows. This has been said elsewhere more poetically, but anyway the idea belongs in the foundation of tech writing project skills.

unlike the chaos model of development where the end result often has little to do with what was originally conceived and nobody quite knows how they ended up where they did.


Practitioners can be so arch in their belief that it works. I don't call it prototyping, I call it muddling. It leads a company down a one-way dead-end rocky road.



Gene Kim-Eng


"Do you feel you've learnt by your mistakes here?"
"I think I have, yes, and I think I can probably repeat them almost perfectly."

OMG, they're completely mad. LOL!


Ned Bedinger
doc -at- edwordsmith -dot- com



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or printed documentation. Features include single source authoring, team authoring,
Web-based technology, and PDF output. http://www.DocToHelp.com/TechwrlList

Now shipping: Help &amp; Manual 4 with RoboHelp(r) import! New editor,
full Unicode support. Create help files, web-based help and PDF in up
to 106 languages with Help &amp; Manual: http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
Agile, SCRUM and Technical Writing: From: Gillespie, Terilyn
Re: Agile, SCRUM and Technical Writing: From: Gene Kim-Eng
Re: Agile, SCRUM and Technical Writing: From: Peter Neilson
Re: Agile, SCRUM and Technical Writing: From: Ned Bedinger
Re: Agile, SCRUM and Technical Writing: From: Gene Kim-Eng

Previous by Author: Re: Agile, SCRUM and Technical Writing
Next by Author: Re: Indexes in the PDF era
Previous by Thread: Re: Agile, SCRUM and Technical Writing
Next by Thread: Re: Agile, SCRUM and Technical Writing


What this post helpful? Share it with friends and colleagues:


Sponsored Ads