Re: Workflow?

Subject: Re: Workflow?
From: Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at>
To: Jody Zolli <jody -dot- zolli -at- gmail -dot- com>
Date: Sun, 28 Aug 2022 16:01:12 +0200

Hello Jody,

you put it very kindly and nice. I am all for it. I also think that being respectful towards other people's work is essential in a workplace to make sure you can work together peacefully, productively, and reach results that ultimately, among other things, ensure the existence of our jobsâ

That's why I think, too: You can only make it about 'give and take', if there is real giving and taking involved in the process: ð

I think along these lines:

* In a workplace where we as writers are part of a workflow, it is about reaching results for the product and its development.
* The developers have certain tasks assigned to them, written and unwritten, which they perform to reach those results.
* We as writers do have the same defined for our tasks.
* When there is an *overlap* in these assignments - which could mean that documentation is supposed to be ready at the time of release - and developers also are *allowed to spend time supporting its creation* - you will be 'in the clear'.
* Again, we can be mutually supportive too, if that has been defined as part of the workflow to reach that result. And company culture supports it.

Otherwise for all the kindness and friendliness you feel and show, at the end of the day a developer (SME) still would be pressed for time too much, eventually.

Kind Regards

Am 28.08.2022 14:15, schrieb Jody Zolli:

This is a great topic! I did a presentation on writer/developer collaboration at a local STC conference some years ago.

I think one of the most important benefits of writers working embedded on agile development teams is that it helps reduce the unequal dependence between writer and developers.

The developers see writers as a time/energy sink, taking but not giving. But when they see we can help contribute to their writing work - executable specs, user stories, functional specifications, on-screen UI options and labels, etc., things get less unequal. When writers are in meetings where design decisions are made and discussed, we ask fewer questions later, and can contribute to design discussions in a meaningful way.

Reducing this unequal dependence can help raise us as true partners in work, and open doors to conversations we could never have had otherwise, and contributions we couldn't make before.


On Sat, Aug 27, 2022 at 6:16 AM Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at> wrote:

Hello There, interesting discussion to start. I always think, in short:
It's best to work with the setup as necessary for product and
stakeholders - and thinking of long-term needs as well as effects.

If you throw your weight about too much, for example, you may get what
you need once - but people will be irritated next time around. The third
time it won't work at all.

Yes, I also made some useful suggestions, regarding GUI design or menu
When you keep in mind what 'hangs on' the whole story you may become
aware that this is not an easy question to answer, really.

Very important is company culture and the understanding of the role a
technical writer should have - or has - in the overall process.
It easily happens that the (sometimes highly) competitive atmosphere
prevents good suggestions or input to be taken - especially in a
'public' place like a meeting that has all stakeholders present: such as
a Sprint review.

I am advocating a peaceful and productive collaboration - but fear of
being misrepresented as regards skills in such surroundings can easily
prevent that.

Crucial also to me can be what the actual 'definition of done' requires:
If the documentation is *not* part of that in actual fact developers are
not asked to support its creation as part of their tasks. Which also
means that they have to focus on (other) tasks required of them.
I think a lot depends on this: Do developers have it as part of their
working tasks - or not? Is t possible for them, in real life, to - for
example - 'log work' (as the Jira term has it) on a documentation

I spent a lot of time in review meetings. I would say though, since
setups changed, workplaces too, it was about 5/10.

Last but not least: I love to take part in it. It makes a lot easier.
Yet, its also important to get a true understanding of the product
design, the actual 'what is meant to do?' idea.

Happy reviewing and documenting!


Am 26.08.2022 20:42, schrieb Peter Neilson:

I think the worst case is when the user interface (and perhaps even
more) changes after the documentation is finished. Bug reports from the
field come in claiming the docs are wrong, even if the last-minute
revisions introduce real bugs.

"Why can't you just change a few words, and maybe a screen shot or
two?" say the guys in software dev. Back when manuals were photo-offset
printed, on a ten-week lead time, there was no way to correct the
documentation except to wait for the next release.

Of course there is always the difficulty of trying to get info from a
recalcitrant dev team. "We don't have time for that." On one occasion a
writer put into the review copies, "For any questions about [this
product] call 617-879-xxxx any time, day or night." Dev guy said, "Hey
you can't say that. That's my home phone number!" We told him, "We
won't say that if we get the info we asked for three months ago."

Visit TechWhirl for the latest on content technology, content strategy and content development |


You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at

Looking for the archived Techwr-l email discussions? Search our public email archives @


Re: Workflow?: From: Peter Neilson
Re: Workflow?: From: Nina Barzgaran
Re: Workflow?: From: Jody Zolli

Previous by Author: Re: Workflow?
Next by Author: Re: Workflow?
Previous by Thread: Re: Workflow?
Next by Thread: Re: Workflow?

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

Sponsored Ads