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.
Subject:Re: Style Guide for UNIX? From:Janice Gelb <Janice -dot- Gelb -at- Sun -dot- COM> To:techwr-l -at- lists -dot- techwr-l -dot- com Date:Sun, 19 Oct 2008 11:49:37 +1100
> I worked at Sun for many years, and I understand you work there now.
> I'm sure Solaris is second nature to you, and you understand exactly
> what you're doing when you write a command line procedure. You've
> probably not only walked through those procedures, but corrected them or
> filed bugs when they don't work as the engineer intended.
> However, I've worked with many writers who are unfamiliar with UNIX
> commands, and I've had to review and correct their documents. UNIX isn't
> intuitive, and if you "sort of" have an idea of what it means, it's not
> the same as knowing what it means.
> So my comment was just cautionary. It's relevant especially if you're
> unfamiliar to the point that you don't know about its case-sensitivity.
> My message was - when you write up a UNIX procedure, be careful to
> either get it right on your own, or consult your SME before you change
> the smallest thing.
I think that any time you aren't sure you understand
a step-by-step procedure you need to consult your SME,
no matter which OS you're documenting. I'm afraid I
don't agree that specifically for UNIX documentation
you need to consult your SME "before you change the
smallest thing." Changing "3. cd to the directory" to
"3. Change to the directory using the cd command" is
not a change that needs to be brought to an SME for
Janice Gelb | The only connection Sun has with
janice -dot- gelb -at- sun -dot- com | this message is the return address
ComponentOne Doc-To-Help 2009 is your all-in-one authoring and publishing
solution. Author in Doc-To-Help's XML-based editor, Microsoft Word or
HTML and publish to the Web, Help systems or printed manuals. http://www.doctohelp.com
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-