[CentOS-docs] A Question of Style

Wed Dec 24 02:04:27 UTC 2014
Karsten Wade <kwade at redhat.com>

On 12/23/2014 05:02 PM, Akemi Yagi wrote:
> On Tue, Dec 23, 2014 at 4:29 PM, PatrickD Garvey
> <patrickdgarveyt at gmail.com> wrote:
> 
>> 
>> I'm not referring to the username used by a particular person
>> while using a CentOS community resource. I'm trying to understand
>> if the document example should use an actual person's username (a
>> security risk increase. That's half that person's credentials.)
>> or a pattern that refers to no one, such as "username".
>> 
> 
> Perhaps you are thinking of the examples found on a page like this
> one:
> 
> http://wiki.centos.org/HowTos/I_need_the_Kernel_Source
> 
> Depending on whether a command is supposed to be run by root or by
> a non-root user, the command line prompt changes between:
> 
> [root at host]#
> 
> and
> 
> [user at host]$
> 
> Akemi

Ah, yes, that makes sense (as to what Patrick is asking, and your reply.)

I've tended to prefer to avoid all that, though, but that is based in
my experience in specific tech writer teams. (Fedora Docs and RHEL docs.)

Rather than require one to be logged in as one user(type) or another,
I would suggest we consider dropping the command prompt entirely and
focus on making the command work /no matter what/. E.g.:

chmod 744 /path/to/file
ls -hal /path/to file

v.

su -c "chmod 744 /path/to/file"
su -c "ls -hal /path/to/file":

This used to be consistent in Red Hat documentation, but I'm not sure
of the current practice. I'd definitely consider the benefits of
aligning with upstream RHEL docs in this case.

Anyway, the point is to create a command that is more like ... well,
like this:

https://fedoraproject.org/wiki/Help:Wiki_syntax_and_markup#Writing_Example_Commands

... that is, a command that works regardless of which user is logged
in and whether 'sudo' is enabled or not. (If no sudo, then one should
have the root password or the problem to solve is different (getting
root access); if one has sudo enabled, then it's simpler to move from
'su -c' to 'sudo'.)

Just another way to look at it. And I think we need a bit more
information on usptream doc usage as that may drive a decision a bit
so whatever we do lines up easily with that.

- Karsten
-- 
Karsten 'quaid' Wade        .^\          CentOS Doer of Stuff
http://TheOpenSourceWay.org    \  http://community.redhat.com
@quaid (identi.ca/twitter/IRC)  \v'             gpg: AD0E0C41