Open Stack

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


   
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20150721/60e288e6/attachment-0001.html>