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.
Hooray for Lauren! I have to thank you for the time you took to clarify
things, just in case I'm ever in a similar situation (Unix/software wise,
that is, I've been in many similar hardware/product situations).
Also, dear Anon, it sounds like your instincts are good and you're in a
tough situation. 'd like to encourage you to heed other suggestions to
research as much of the associated software as you can. You can resolve some
of your basic questions about whether descriptions are complete enough, or
their accuracy, if you can step through the procedures. "Then," you can go
to the SME with your changes and say, "I'd like to verify my understanding
of x." You'll probably also end up with some specific questions to ask, such
as Lauren mentioned (below), or even more specific:
"New database files directory" requires the same type of discussion as
"script directory." Some form of consistent reference to the _thing_ needs
to be established. Is this a "new" database? An "xyz system" database? Or
what? Find a way to consistently refer to the thing being built and refer
to the thing the same (or similar enough) way each time.
Generally, I've found that SME's tend to be busy, and maybe crusty, so they
tend to respond best when they're asked specific questions about things,
rather than being a hit with a global one, especially after a long night's
coding (start-up?). I even find that I respond best to specific questions,
being crusty at times (not on purpose, mind you :-).
Doing background research also helps ensure that you don't end up a
glorified typist/formatter and that you gain knowledge to help your career.
Even if they have time constraints and just want someone to reformat the
document and make it pretty, do as much as you can. But as tactfully as
possible--be mindful how hard it is to take someone else's perspective when
one is buried in the work.
Good luck!!
Kathleen
On 6/27/07, Lauren <lt34 -at- csus -dot- edu> wrote:
>
> Hey Anon,
>
> I used to work with Unix. I engineered web systems and wrote apps and
> stuff. Plus, I documented what I did. You really don't need to say a
> lot,
> but some things in your example are stated a little badly.
>
> > 4. Create db_env_{SID}.bat:
> >
> > a. DB and ORACLE_SID set to {SID} needs to be created.
> >
> > b. ORADIR oracle_home.
>
> "a" should probably be re-worked, but you will need to talk to the
> developer
> because I haven't worked with Oracle. Is is it, "set DB and ORACLE_SID to
> {SID}" or is it "Create {SID} and set DB and ORACLE_SID to {SID}"?
>
> Change b to:
>
> "Set ORADIR to oracle_home."
>
> If you have font options, then "ORADIR" and "oracle_home" should be in the
> appropriate fonts. Presumably bold for "ORADIR" and italics for
> "oracle_home."
>
> >
> > c. SCRDIR script directory.
>
> Change to:
>
> "Set SCRDIR to the script directory."
>
> "The script directory" may need more explanation, like "current script
> directory" or "script directory for the current system" or "script
> directory
> for the new database." Some convention should be adopted for how to refer
> to the new _things_ being built.
>
> This sounds like it is the directory that the administrator has determined
> for the particular system.
>
> > d. Point the FILDIR directory where you want the database
> > files to
> > be created.
> >
> > Note that it will append the database files to it so the path
> > will be FILDIR\DB\.
>
> Okay, this is just badly written.
>
> Change to:
> "Point FILDIR to the new database files directory."
>
> "New database files directory" requires the same type of discussion as
> "script directory." Some form of consistent reference to the _thing_
> needs
> to be established. Is this a "new" database? An "xyz system"
> database? Or
> what? Find a way to consistently refer to the thing being built and refer
> to the thing the same (or similar enough) way each time.
>
> Change to:
> "Note: The FILDIR pointer will append new database files to this path so
> that the database file path will be FILDIR\DB\."
>
> You might want to trim the above note, but that explains what is
> happening.
> "DB" should be offset with the font you use for variables, unless the
> developer intends that "DB" is the directory name.
>
> > 5. Create init{SID}.ora:
> >
> > a. In the Diagnostics and Statistics section, change the
> > location of
> > the diagnostic files accordingly.
> >
> > b. In the File Configuration section, set the location of the
> > control files accordingly.
> >
> > c. In the Miscellaneous section, change the compatible
> > and db_name
> > parameters accordingly.
>
> Argh. I hate sentences written this way. Here's how I would address
> this.
>
> 5. Create init{SID}.ora and make the appropriate changes in the sections
> that follow.
>
> a. Diagnostics and Statistics
> - Change the location of the diagnostic files.
>
> b. Configuration
> - Set the location of the control files.
>
> c. Miscellaneous
> - Change the compatible and db_name parameters.
>
> "Appropriate" should probably be more informative, but will likely follow
> whatever convention is adopted for "script directory" and "new database
> files directory."
>
> Lauren
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> 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 kathleen -dot- eamd -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/kathleen.eamd%40gmail.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.
>
>
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-
