Re: convention for putting a variable in a path...

[Stuart Burnfield <sburnf -at- au1 -dot- ibm -dot- com>]

Sean said:
> Anyone working on Linux at the technical level will know
> what the init scripts are and where to find them and how
> to use them. User of deb or rpm -based systems will know
> the differences.

"If they don't already know, they don't need to know." I'm not saying this
is wrong, but it's the sort of assumption I think we as TWs need to be
careful of. Kimberly's documentation might be aimed at 'a reasonably
knowledgeable/experienced Linux administrator' but there are shades of grey
in that job description. You could have an experienced sysadmin who hasn't
had much to do with Linux before.

- The company could be replacing some ageing UNIX gear with Linux, so their
very experienced sysadmin may know all about init scripts but not be aware
that their location is a little different on Linux.

- The Linux support guy just quit last week, so the Windows support guy has
been told to look after the Linux boxes from now on.

- After a company takeover, the little fish's Linux admin function has been
'centralised' in a different city where the big fish has its HQ.

- a Windows-only or Mac-only software development shop is thinking of
providing a Linux client for their product. One of the developers is told
to set up a Linux development environment (including Kimberly's repository)
and see what's involved.

And so on. Of course we shouldn't have to teach Linux or computing basics
in an application manual. It's reasonable to specify an assumed minimum
level of knowledge in the Preface. But you do need to be aware of how many
people you might be telling, "Sorry, we don't want your money. Try our
competitors."

In my experience, a very common question for sysadmins to want to ask about
an software installation is "What are you going to change (or what did you
just change) on my system?" If Kimberly's product is likely to be installed
by some people who haven't done much Linux admin yet, and Kimberly's
company doesn't want to exclude some potential customers on the basis that
their sysadmin is unworthy, it's reasonable to provided them with the
information.

To get back to the original question, in this situation if there were only
two or three items I would just list the full paths. More than that and I'd
go with Martha's style (italicized N).

Regards

Stuart

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

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content 
delivery. Try it today!. http://www.webworks.com/techwr-l 

Doc-To-Help includes a one-click RoboHelp project converter. It's that easy.  Watch the demo at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -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/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.