[openstack-dev] [OpenStack-docs] [ironic] Admin guide in-tree?

Jay Faulkner jay at jvf.cc
Tue Oct 11 23:00:01 UTC 2016


We are eager to improve our documentation, but I think quite a few of us who work on Ironic documentation have a strong preference to keeping those documents in-tree. This allows us to enforce contributors having documentation changes or additions merge at the same time or in close proximity to the code changes and is much easier for us to interact with. I have the willingness to help implement admin guides in-tree sooner, but if the docs team doesn't want this yet obviously there's nothing to help with.

As for what to do today today; I agree with Ruby on this entirely. I'm adding an item to Monday's Ironic meeting agenda to reach consensus on what our project will do in the meantime. My recommendation will be option B as listed by Ruby; build out a better admin-guide in tree as part of our developer docs, and migrate them over, just like we did for the install guide, when the work to allow in-tree admin guides is complete.

Thanks,
Jay Faulkner

On Oct 11, 2016, at 9:38 AM, Ruby Loo <opensrloo at gmail.com<mailto:opensrloo at gmail.com>> wrote:

>From my point of view, the rush is so that we can be more efficient with all of our time/efforts. In ironic, we have a bit of a mess. We now have duplicated (and perhaps out-of-sync) admin-related information in our developer docs [1] as well as in the official admin guide [2] -- the latter content was added but I am unaware of that knowledge/coordination being done with the ironic community :-(

Should we :
A. move our admin-related information from our developer docs to the existing admin guide; then move the admin guide to the new in-tree solution later

B. replace what is in the existing admin guide with a pointer to the developer docs; then move the admin content to the new in-tree solution later

C. status quo until the new in-tree solution is available

--ruby

[1] http://docs.openstack.org/developer/ironic/
[2] http://docs.openstack.org/admin-guide/baremetal.html


On Mon, Oct 10, 2016 at 7:07 PM, Lana Brindley <openstack at lanabrindley.com<mailto:openstack at lanabrindley.com>> wrote:
On 10/10/16 16:25, Andreas Jaeger wrote:
> On 2016-10-10 01:37, Steve Martinelli wrote:
>> On Oct 9, 2016 6:57 PM, "Lana Brindley" <openstack at lanabrindley.com<mailto:openstack at lanabrindley.com>
>> <mailto:openstack at lanabrindley.com<mailto:openstack at lanabrindley.com>>> wrote:
>>>
>>> Why the rush?
>>
>> I think its more eagerness than rush. Project teams made a lot of head
>> way with the API ref and install guides being in-tree that they want to
>> keep the momentum with the admin guide.
>
> Those teams are more than welcome to contribute today to the
> openstack-manuals repository! Is there anything we can help these?
>
> Andreas
>

Yes, Andreas makes a good point. If there's content you want in the guides now, we can help you with that.

Lana

--
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com<http://lanabrindley.com/>


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org?subject:unsubscribe<http://OpenStack-dev-request@lists.openstack.org/?subject:unsubscribe>
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


__________________________________________________________________________
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request at lists.openstack.org<mailto:OpenStack-dev-request at lists.openstack.org>?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20161011/7ef37ec7/attachment.html>


More information about the OpenStack-dev mailing list