TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
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.
-Jody
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
> labelling.
> 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
> ticket?
>
> 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!
>
> Nina
>
> 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
