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.
Caroline makes some very good points here. You need to ensure that you
have sufficient time after code freeze to make all your documentation
updates. Here, we do a first round of QA after code freeze. Invariably,
testers find bugs that end up changing the UI, etc. This in turn causes
further updates to the documentation.
Then, we do a second round of QA where we test the documentation along
with the new features, to verify the documentation is correct and
complete, and to regression test the application after the new release
is added.
Of course, I end up making changes even after round two. Not much can be
done to avoid that. I try to mitigate the damage by doing all my writing
as early as possible, but the screenshots inevitably have to be updated
at the eleventh hour.
We also have release notes to deal with. As Caroline mentioned, they
should not include screenshots and should give the technical summary of
the new features, bug fixes, etc. I can't think of a release where
they've been nailed down as early as I'd like.
Now we are getting into translation and localization, which adds a whole
other wrinkle to scheduling.
I recommend aspirin and St John's Wort.
Chris
-----Original Message-----
From: techwr-l-bounces+cvickery=arenasolutions -dot- com -at- lists -dot- techwr-l -dot- com
[mailto:techwr-l-bounces+cvickery=arenasolutions -dot- com -at- lists -dot- techwr-l -dot- com]
On Behalf Of Caroline Tabach
Sent: Thursday, October 25, 2007 5:33 AM
To: Zen C
Cc: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: Re: Workflow for a release
You should first define what a release note contains.
Where I work, for a new release we add details to the user guides.
The release notes contain a short note about each new feature.
Screen shots do not go into the Release notes.
Release notes can also contain details about features that did not get
into
the user guide.
There should indeed be a cut off point for updating user guides and
creating
help files.
Release notes are typcially completed at the last minute as they may
contain
details of bugs/limitations.
For next time.
You need to plan,
Generally the developers should know what they are supposed to develop,
this
may be decided by their managers. There should be some sort of content
for
the next defined release.
You need to get your hands on the list of contents for the release, or
be in
contact with the programmers to see what they are doing.
They might have specs, or they might have meetings discussing
development,
As an only TW, you will not have time to attend all meetings and write
as
well, but you should be on the invitation list for the meetings so you
will
know they are happening. After the meeting find out what happened, try
and
be on the list of people who get sent the specs. When they are
developing,
they should have dates for completing features, try to get that info too
When a software version goes to QA it should also have a list of new
features, that is something that can help you too.
All these things together should provide you with a list of what is
being
developed and when.
If you have such a list and it is approved by someone, you have a piece
of
paper which together with your boss you can say, these are the features
I am
going to write about. Anything not on this list needs special approval!
Are you working in a country where the GUI designers write good English,
if
not, offer to check the GUI for them, and you will also know what is
being
developed.
User guides and help should often be completed a certain time before
software release so that they can go through QA, talk to QA in your
company
to get an idea of these dates.
Maybe the points above can be of help to you
On 10/25/07, Zen C <zenizenc -at- gmail -dot- com> wrote:
>
> Hi,
>
> I am working on release note and have been working on it for two
weeks.
> While everything is finalized, sent to the responsible parties and
suppose
> to go out on Friday they come up with 6 new changes that I have to add
to
> the release notes and incorporate to the help. This has been the case
for
> the last 3 release I did and luckily this time my boss took her stand
and
> said that we need a cut off date for future releases. I am the only
tech
> writer for the company so everything else is on hold as I am editing
the
> documents a million times cos of all the GUI changes and new items
they
> are
> bringing in.
>
> Does anyone one have a good work flow they follow, or a rough idea on
what
> the best cut off dates are. I know it depends on the company and a lot
of
> other factors, but it will be great if I can get some idea to suggest
> something feasible.
>
> Have a great day!
>
> Zen.
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> Create HTML or Microsoft Word content and convert to Help file formats
or
> printed documentation. Features include support for Windows Vista &
2007
> Microsoft Office, team authoring, plus more.
>http://www.DocToHelp.com/TechwrlList
>
> True single source, conditional content, PDF export, modular help.
> Help & Manual is the most powerful authoring tool for technical
> documentation. Boost your productivity! http://www.helpandmanual.com
>
> ---
> You are currently subscribed to TECHWR-L as caroline -dot- tabach -at- gmail -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/caroline.tabach%40gma
il.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/ for more resources and info.
>
>
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as cvickery -at- arenasolutions -dot- com -dot-
Create HTML or Microsoft Word content and convert to Help file formats or
printed documentation. Features include support for Windows Vista & 2007
Microsoft Office, team authoring, plus more. http://www.DocToHelp.com/TechwrlList
True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
