Open Stack

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

I think that, for our purposes, writing "restart the service" in prose
is fine for non-OS specific books. Obviously, use the command in the
Install Guide, though. This falls under 'basic OS knowledge'.

L

On 22/07/15 06:25, Meg McRoberts wrote:
> One can always say "for example" or something to avoid implying that OpenStack can only bedeployed on the distros that are listed.
> +1 for more symlinks.  And, of course, our job is not to teach people how to use the operating system,but the subtle differences between distros can mess people up.  For example, an experienced Debian/Ubuntuperson who is deploying on RHEL/Centos may need a hint when RHEL/Centos does something differently.
> Another thought is to put details about, say, differences in "restart" between distros and then link to that wheneverwe include a restart step in a procedure.  I'm not sure of the details here.
> I admit that, when I am following a procedure, I tend to glance at the prose then copy-and-paste the command fromthe docs into my shell.  As someone else mentioned, this is probably even more true for people who are less comfortablewith the English language.
> 
>  
>       From: Matt Kassawara <mkassawara at gmail.com>
>  To: Gauvain Pocentek <gauvain.pocentek at objectif-libre.com> 
> Cc: "openstack-docs at lists.openstack.org" <openstack-docs at lists.openstack.org> 
>  Sent: Tuesday, July 21, 2015 6:41 AM
>  Subject: Re: [OpenStack-docs] distro-specific commands in guides
>    
> Outside of the installation guide, we should avoid using any commands specific to distributions or packages because our audience may incorrectly assume the documentation limits how and where they can deploy OpenStack. Similarly, we should avoid spelling out general OS commands (such as making symlinks and showing network interfaces) because our audience should already understand how to use the OS before deploying OpenStack.
> 
> 
> On Mon, Jul 20, 2015 at 10:24 PM, Gauvain Pocentek <gauvain.pocentek at objectif-libre.com> wrote:
> 
> Le 2015-07-20 14:44, Christian Berendt a écrit :
> 
> On 07/19/2015 06:26 PM, Tom Fifield wrote:
> 
> On the other hand, I agree that it is a fair assumption that our readers
> understand how to do a service restart - this is a fairly basic and
> essential sysadmin practice.
> 
> 
> +1
> 
> Maybe we should add a list of required and assumed previous knowledge.
> 
> 
> I can start this list but for now service restart is the only obvious element I can think of. Maybe we could just leave it at that and simply add a "don't write CLI samples for service restarts, except in the install guide" to the conventions.
> 
> How does it sound?
> 
> Thanks,
> Gauvain
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> 
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 
> 
>    
> 
> 
> 
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> 


- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJVrrmAAAoJELppzVb4+KUyfeYH/ixyRSx9kKZRrUqoH7r7H03Q
ZKK0BGxZyfeed2Iw8d4rBD6QC9TxZXYJHGP7cPGecGfgy/7gA9zkwgLTo8xWj4GF
roh7I5PwOVSg/s9VhdCYL1g50yPI7BrhMMW7ZRVC5URS6oRN7vd8VglrFU2hH+NF
nVvYWsS+WMYwVrAnRiCNtwdzztNuMUX0N1Cj4Ondf5SYgU+e35nR70LPYrhgSaQJ
3YGvTAqJDd9R3O6T1tbmDXZleWl9Q7hQI/OdhCaCOdCfsLF/1u22obBx398Y7J54
bNddxK3HMyf9q0yY16TuipVkKIqZwK22DUZ/h0j/wA1Uff1v4FVGCJ+flCD9ZOg=
=HBhg
-----END PGP SIGNATURE-----