Re: TECHWR-L Digest, Vol 200, Issue 10

[Sue Jones <suej_be -at- yahoo -dot- com>]

I love this topic.
I must admit that one of the manuals I'm most proud of is one that I wrote during a design overview meeting I had with the developer. She had some idea of what she wanted to do and we spent some time working everything out. I took all of the notes and design decisions from our meeting and went ahead and created an 'interim' manual.ÂWe knew that she wouldn't be able to start her implementation for some weeks.
A few months later, when she was ready to start work, she used my 'interim' manual as her spec. It was the single most satisfying feeling when she told me what she'd done. We were both really happy with the outcome. Especially as it then only took me a day or so to finalize and release the manual.
Wishing you all a great week!
Grt. Mrs. Sue Baars-Jones "To achieve greatness...start where you are, use what you have, do what you can." Arthur Ashe. 

    On Monday, August 29, 2022 at 07:55:10 AM GMT+2, techwr-l-request -at- lists -dot- techwr-l -dot- com <techwr-l-request -at- lists -dot- techwr-l -dot- com> wrote:  
 
 Send TECHWR-L mailing list submissions to
ÂÂÂ techwr-l -at- lists -dot- techwr-l -dot- com

To subscribe or unsubscribe via the World Wide Web, visit
ÂÂÂ http://lists.techwr-l.com/mailman/listinfo/techwr-l
or, via email, send a message with subject or body 'help' to
ÂÂÂ techwr-l-request -at- lists -dot- techwr-l -dot- com

You can reach the person managing the list at
ÂÂÂ techwr-l-owner -at- lists -dot- techwr-l -dot- com

When replying, please edit your Subject line so it is more specific
than "Re: Contents of TECHWR-L digest..."


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

Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

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




Today's Topics:

 1. Re: Workflow? (Jody Zolli)
 2. Re: Workflow? (Nina Barzgaran)
 3. Re: Workflow? (Peter Neilson)
 4. Re: Workflow? (John Garison)
 5. Re: Workflow? (Nina Barzgaran)


----------------------------------------------------------------------

Message: 1
Date: Sun, 28 Aug 2022 08:15:28 -0400
From: Jody Zolli <jody -dot- zolli -at- gmail -dot- com>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Workflow?
Message-ID:
ÂÂÂ <CAGoeYZcnGgLtoHA0Bf3dDT5_4PdqXTGqODLbAy=uM=uo3Z4PjA -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset="UTF-8"

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."
> >
>
>


------------------------------

Message: 2
Date: Sun, 28 Aug 2022 16:01:12 +0200
From: Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at>
To: Jody Zolli <jody -dot- zolli -at- gmail -dot- com>
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Workflow?
Message-ID: <00378566367e527d4f0ed6ef78bf0608 -at- barzgaran -dot- at>
Content-Type: text/plain; charset=UTF-8; format=flowed

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
Nina

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.
> 
> -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."
>>> 

------------------------------

Message: 3
Date: Sun, 28 Aug 2022 10:52:39 -0400
From: Peter Neilson <neilson -at- windstream -dot- net>
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Workflow?
Message-ID: <0f88cc2d-4c1b-df68-52cc-8ec3a0752d38 -at- windstream -dot- net>
Content-Type: text/plain; charset=UTF-8; format=flowed

Must have support of management as well, and not get fooled by people 
who have been instructed to ignore you. We once had a manager who 
actually said, "No one talks to my developers except through me. If you 
have a question I have to approve it first." This was long before Agile 
stuff, and was at a company where the management theory was, "Solve 
problems at the lowest level before escalating.".

Even with Agile, you can find that the entire discussion is about stuff 
totally unrelated to user interface or even API, and your mention of 
documentation is met with, "Yes, yes, of course. We'll deal with that 
later when we have something to report. Right now assume that nothing 
will have changed."

On 8/28/22 10:01, Nina Barzgaran wrote:
> Subject:
> Re: Workflow?
> From:
> Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at>
> Date:
> 8/28/22, 10:01
> 
> To:
> Jody Zolli <jody -dot- zolli -at- gmail -dot- com>
> CC:
> techwr-l -at- lists -dot- techwr-l -dot- com
> 
> 
> 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
> Nina
> 
> 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.
>>
>> -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
> 
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> 
> You are currently subscribed to TECHWR-L as neilson -at- windstream -dot- net -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


------------------------------

Message: 4
Date: Sun, 28 Aug 2022 21:42:05 -0400
From: John Garison <vwritert -at- gmail -dot- com>
To: Andrew Harvie <withanie -at- gmail -dot- com>
Cc: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Subject: Re: Workflow?
Message-ID:
ÂÂÂ <CAFJnaP6DW+P2=yuzD_1E92-aLPMnjDw9cEUjEtn6VD3PuU-G=A -at- mail -dot- gmail -dot- com>
Content-Type: text/plain; charset="UTF-8"

I've been working with the same development team for 10 years and I am
fully embedded with the design and development efforts. I get access to
everything from customer focus groups to early wireframes and work on UI
wording before the stories are shared with the developers and testers. I
get to approve all the text on the screen and error messages. One team, one
goal.

On Thu, Aug 25, 2022, 9:50 AM Andrew Harvie <withanie -at- gmail -dot- com> wrote:

> The following question arises from idle curiosity. I'm not looking for
> advice or help for myself, but if a valuable discussion ensues then so much
> the better.
>
> For a technical writer, I believe that the ideal time to learn about a new
> feature is while it's in the early stages of development. If you can be
> there while the use-cases are being discussed and the possible solutions
> are being evaluated, you gain an understanding that will help when writing
> the documentation.
>
> But out there in the real world, how often is that the case? If there is a
> scale where 10 represents a workflow that sees the technical writer invited
> to planning meetings and 0 represents the technical writer only learning of
> a feature when the programmers have finished their work and tossed it over
> the wall an hour before build time, where do you find yourself on that
> scale?
>
> --
>
> -- Andrew Harvie
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | https://techwhirl.com
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as vwritert -at- gmail -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
>


------------------------------

Message: 5
Date: Mon, 29 Aug 2022 02:51:49 +0200
From: Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at>
To: Peter Neilson <neilson -at- windstream -dot- net>
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Workflow?
Message-ID: <ff4b71266e072a8fdc0c1de7a573407f -at- barzgaran -dot- at>
Content-Type: text/plain; charset=UTF-8; format=flowed

That's a very sad experience, a manager instructing others to ignore 
you. Thanks for sharing.

I think a lot depends on perception, too as far as feeling competitive 
is concerned. Sometimes people may feel it to be more wise to take 
precautions not to expose any weaknesses - and thus keep their mouths 
shut.
When I see that kind of behaviour I feel it's rather sad. I have seen it 
happen in many places, university, government offices or businesses, you 
name it.
Sometimes a competitive atmosphere gets started due to company culture. 
Sometimes it's what people bring with them - from previous experience, 
mindset or education.

I am lucky these days.
In general, trying to 'fight' a (latent) conviction of any kind can be 
impossible: be that management ideas or the underlying fears created by 
business culture.
I always felt a little like a missionary: try making it better, if 
there's fear - or prejudice. Make clear that goodwill is important.
We are people after all. We depend on each other.

Best
Nina

Am 28.08.2022 16:52, schrieb Peter Neilson:

> Must have support of management as well, and not get fooled by people 
> who have been instructed to ignore you. We once had a manager who 
> actually said, "No one talks to my developers except through me. If you 
> have a question I have to approve it first." This was long before Agile 
> stuff, and was at a company where the management theory was, "Solve 
> problems at the lowest level before escalating.".
> 
> Even with Agile, you can find that the entire discussion is about stuff 
> totally unrelated to user interface or even API, and your mention of 
> documentation is met with, "Yes, yes, of course. We'll deal with that 
> later when we have something to report. Right now assume that nothing 
> will have changed."
> 
> On 8/28/22 10:01, Nina Barzgaran wrote: Subject:
> Re: Workflow?
> From:
> Nina Barzgaran <nina -dot- barzgaran -at- barzgaran -dot- at>
> Date:
> 8/28/22, 10:01
> 
> To:
> Jody Zolli <jody -dot- zolli -at- gmail -dot- com>
> CC:
> techwr-l -at- lists -dot- techwr-l -dot- com
> 
> 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
> Nina
> 
> 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.
> 
> -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

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

You are currently subscribed to TECHWR-L as neilson -at- windstream -dot- net -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 
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy 
and content development | https://techwhirl.com

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

You are currently subscribed to TECHWR-L as nina -dot- barzgaran -at- barzgaran -dot- at -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

------------------------------

_______________________________________________
You are currently subscribed to
TECHWR-L.
To unsubscribe send a blank email to
http://lists.techwr-l.com/mailman/listinfo/techwr-l
Send administrative questions to admin -at- techwr-l -dot- com -dot- 

Visit
http://www.techwhirl.com/ for more resources and info.

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives

End of TECHWR-L Digest, Vol 200, Issue 10
*****************************************
  
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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