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
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 | https://techwhirl.com
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
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.
Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com
Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives
- Re: Workflow?, Peter Neilson
Search our Technical Writing Archives & Magazine