<div dir="ltr">
<p style="margin-bottom:0in;line-height:100%">Hi to everyone!</p>
<p style="margin-bottom:0in;line-height:100%">
</p>
<p style="margin-bottom:0in;line-height:100%">I am rising this
thread again because I am willing to be involved in the matter if the
community decides in favour of the proposed change, cause I am
strongly convinced that it can improve the doc contributors'
experience. Lets finally dot all the 'i's =)</p>
<p style="margin-bottom:0in;line-height:100%">I have already
discussed the matter with Lana, took into consideration your opinions
(you have kindly mailed in this thread), and here is what I came up
with.</p>
<p style="margin-bottom:0in;line-height:100%"><b>Problem
Description</b></p>Basing on my own
experience and the experience of my colleagues, the information for
the docs contributors located on wiki sometimes contains outdated
info and can be improved by restructuring.
<p style="margin-bottom:0in"><b>Proposed Solution</b></p>We propose to initiate the creation of the Documentation
Contributors Guide targeted at the contributors to the OpenStack
documentation that will cover the following issues:
<ul><li>Markup conventions</li><li>Terminology and writing syntax conventions</li><li>Screenshots and topologies conventions</li><li>Documentation structure</li><li>Gerrit workflow (HowTo)</li><li><i>anything else interesting to
the community </i>
</li></ul>
<p style="margin-bottom:0in"><b>What To Be Done</b></p>This task can be
resolved in two steps:
<p style="margin-bottom:0.2in;line-height:100%"><i><u>STEP 1:</u></i> moving the
cleaned up content from wiki.</p>
<p style="margin-bottom:0.2in;line-height:100%">As we are treating
our documentation as the code and willing others to do so, we propose
to relocate all the conventions, how to instructions and any docs
contributor-related things to 'somewhere'. probably to<a href="http://docs.openstack.org/infra"> http://docs.openstack.org/infra</a> (as
this was proposed earlier by Christian) as a single-entry, full, and
neatly organized guide that answers questions that arise in the docs
creation workflow. <br><br>The wiki is definitely not much
convenient, it has narrowed functionality and lacks a number of
features that have become essential part of any internet user
nowadays, such as search, proper navigation, and some others.</p><p style="margin-bottom:0.2in;line-height:100%"><span style="font-weight:normal">Moving
things </span><span style="font-weight:normal">around</span><span style="font-weight:normal">
will noways influence its openness to the community or make the
conventions less flexible. This will only unify and simplify the
process. Besides, the docs contributor guide should be definitely
treated more seriously by the contributors than things placed in
wiki.</span></p>
<p style="margin-bottom:0.2in;line-height:100%"><span style="font-weight:normal"><i><u>STEP
2:</u></i> discuss and add the content that's missing from the
'I-am-a-contributor' position. </span>
</p>
<p style="margin-bottom:0in"><b>Problems to Discuss</b></p>Lets answer the main
questions and plan the future basing on the decision made:
<p style="margin-bottom:0in;line-height:100%">1. The first and the
most important question is:</p>
<p style="margin-bottom:0in;line-height:100%;text-align:left;margin-left:40px"><b>Documentation
Contributor Guide: to be or not to be?
</b></p>
<p style="margin-bottom:0in;line-height:100%">2. Where is the
most appropriate location for it?</p>
<p style="margin-bottom:0in;line-height:100%">I agree that
<a href="http://docs.openstack.org/infra">http://docs.openstack.org/infra</a> is the best place, but before taking
any steps in this direction, we should thoroughly discuss what kind
of content this should include with the
its owner, and find a compromise. Jeremy,
did I understand your point right?</p>
<p style="margin-bottom:0in;line-height:100%">Thank you all for
reading this up to the end, and for any feedback on the matter!</p><p style="margin-bottom:0in;line-height:100%">Olga.</p><p style="margin-bottom:0in;line-height:100%"><br></p>
<div class="gmail_extra"><br><div class="gmail_quote">On Thu, May 28, 2015 at 10:03 PM, Jeremy Stanley <span dir="ltr"><<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 2015-05-28 19:24:15 +0200 (+0200), Christian Berendt wrote:<br>
[...]<br>
<span class="">> If we confirm to move the content into the already existing<br>
> developers guide what do we have to do to proceed?<br>
<br>
</span>Seems like a great idea for anything that's a fit. Just keep in mind<br>
that we want to keep infra-manual focused on topics that are<br>
relevant to community infrastructure interactions for the majority<br>
of project-teams in our ecosystem, and not drill down into workflow<br>
recommendations which only apply to some specific projects. For one<br>
thing, the Infra team doesn't want to become a review bottleneck for<br>
individual project-team documents.<br>
<span class=""><br>
> I think we have to write a spec for docs-specs and I think we<br>
> should discuss this topic with the owner of the developers guide<br>
> (openstack-infra mailinglist?).<br>
<br>
</span>I'm happy to respond here, but yes you might reach more of the<br>
infra-manual authors on the -dev or -infra MLs.<br>
<span class="HOEnZb"><font color="#888888">--<br>
Jeremy Stanley<br>
</font></span><div class="HOEnZb"><div class="h5"><br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.openstack.org</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><br>
</div></div></blockquote></div><br><br clear="all"><br>-- <br><div class="gmail_signature"><div dir="ltr"><div><div>Best regards,<br></div>Olga<br><br></div>Technical Writer<br><div>skype: gusarenko.olga
</div><div><br></div></div></div>
</div></div>