Open Stack

Hiya,

Indeed a valid question.

Very slightly on the 'include' side here, on the basis of:
1) if someone installing doesn't do the restart, confusing/more 
difficult than normal to track down errors could result in some cases 
(eg using the SQLIte database instead of MariaDB)
2) Readers with a lower level of English probably a) rely more on the 
commands than the text or b) might deal better with explicit instruction
3) in the case multiple services need to be restarted, our more careful 
linewrapping of commands compared with text probably makes it harder to 
miss a service

Where #1/#3 doesn't come into play, and is a nicety to restart the 
service, including a text-based reference seems fine.

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.


Regards,


Tom

On 19/07/15 04:06, Gauvain Pocentek wrote:
> Le 2015-07-19 11:23, Meg McRoberts a écrit :
>> Is it reasonable to think that people just know how to use these commands
>> if we don't include them?
>
> I think it's OK to not include the 'service foo restart' commands.
>
>
>>
>> I tend to favor putting in the appropriate commands for the various
>> distros.
>> For sophisticated audiences, I think it's actually useful to show when
>> different
>> distros have different practices. One possible presentation style is
>> here:
>>
>> http://docs.openstack.org/draft/ha-guide/controller-ha-rabbitmq.html [4]
>>
>> It's compact and I can quickly see the command (sequence) required for
>> the
>> distro I am using.
>
> It does make sense in this example, I'm not sure it would for every
> command in our docs. It is also complicated to maintain and to verify
> (you need to have multiple test systems handy, which is not always
> possible).
>
> Could we recommend adding the commands for "non-obvious" items (package
> names for example), and leaving them out for other items (service
> restart, system reboot, file edition...)? This means defining what we
> assume is obvious and what is not...
>
> Thanks for your feedback Meg,
>
> Gauvain
>
>>
>> meg
>>
>>> -------------------------
>>> FROM: Gauvain Pocentek <gauvain.pocentek at objectif-libre.com>
>>> TO: openstack-docs <openstack-docs at lists.openstack.org>
>>> SENT: Sunday, July 19, 2015 12:45 AM
>>> SUBJECT: [OpenStack-docs] distro-specific commands in guides
>>>
>>> Hi,
>>>
>>> Should we add explicit command about services restart and similar
>>> distro-specific commands in the guides (except the install-guide)? We
>>> have some inconsistencies throughout the guides and IMHO our best shot
>>> at fixing them is probably to not specify the commands to run. Or we'll
>>> end up with way too much maintenance work.
>>>
>>> Bugs I reported/came across that touch this problem:
>>>
>>> https://bugs.launchpad.net/openstack-manuals/+bug/1459130 [1]
>>> https://bugs.launchpad.net/openstack-manuals/+bug/1474879 [2]
>>>
>>> Gauvain
>>>
>>> _______________________________________________
>>> OpenStack-docs mailing list
>>> OpenStack-docs at lists.openstack.org
>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs [3]
>>
>>
>> Links:
>> ------
>> [1] https://bugs.launchpad.net/openstack-manuals/+bug/1459130
>> [2] https://bugs.launchpad.net/openstack-manuals/+bug/1474879
>> [3] http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>> [4] http://docs.openstack.org/draft/ha-guide/controller-ha-rabbitmq.html
>
> Gauvain Pocentek
>
> Objectif Libre - Infrastructure et Formations Linux
> http://www.objectif-libre.com
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs