<div dir="ltr"><div>Thanks Andreas and Bernd for responds!<br><br></div>Please, see my comments inlines.<br><br><div><div><div class="gmail_extra"><br><div class="gmail_quote">On Wed, Jul 1, 2015 at 11:56 AM, Andreas Jaeger <span dir="ltr"><<a href="mailto:aj@suse.com" target="_blank">aj@suse.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">On 07/01/2015 10:33 AM, Olga Gusarenko wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Hi to everyone!<br>
<br>
I am rising this thread again because I am willing to be involved in the<br>
matter if the community decides in favour of the proposed change, cause<br>
I am strongly convinced that it can improve the doc contributors'<br>
experience. Lets finally dot all the 'i's =)<br>
<br>
I have already discussed the matter with Lana, took into consideration<br>
your opinions (you have kindly mailed in this thread), and here is what<br>
I came up with.<br>
<br>
*Problem Description*<br>
<br>
Basing on my own experience and the experience of my colleagues, the<br>
information for the docs contributors located on wiki sometimes contains<br>
outdated info and can be improved by restructuring.<br>
<br>
*Proposed Solution*<br>
<br>
We propose to initiate the creation of the Documentation Contributors<br>
Guide targeted at the contributors to the OpenStack documentation that<br>
will cover the following issues:<br>
<br>
* Markup conventions<br>
* Terminology and writing syntax conventions<br>
* Screenshots and topologies conventions<br>
* Documentation structure<br>
* Gerrit workflow (HowTo)<br>
</blockquote>
<br>
The gerrit workflow should really be part of the infra-manual. Let's avoid duplication with that one.<br></blockquote><div><br><br></div><div>If we put the gerrit workflow to some other place (different from another content location), the remaining information will fit the "Style Guide" name.<br></div><div>And I am against it as it is not convenient for me as for a contributor to refer to different locations while making changing in the docs. I am for a single entry for all the contribution-related staff.<br><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
* /anything else interesting to the community /<br>
<br>
*What To Be Done*<br>
<br>
This task can be resolved in two steps:<br>
<br>
/_STEP 1:_/ moving the cleaned up content from wiki.<br>
<br>
As we are treating our documentation as the code and willing others to<br>
do so, we propose to relocate all the conventions, how to instructions<br>
and any docs contributor-related things to 'somewhere'. probably<br>
tohttp://<a href="http://docs.openstack.org/infra" rel="noreferrer" target="_blank">docs.openstack.org/infra</a> <<a href="http://docs.openstack.org/infra" rel="noreferrer" target="_blank">http://docs.openstack.org/infra</a>> (as<br>
this was proposed earlier by Christian) as a single-entry, full, and<br>
neatly organized guide that answers questions that arise in the docs<br>
creation workflow.<br>
</blockquote>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
The wiki is definitely not much convenient, it has narrowed<br>
functionality and lacks a number of features that have become essential<br>
part of any internet user nowadays, such as search, proper navigation,<br>
and some others.<br>
<br>
Moving things aroundwill noways influence its openness to the community<br>
or make the conventions less flexible. This will only unify and simplify<br>
the process. Besides, the docs contributor guide should be definitely<br>
treated more seriously by the contributors than things placed in wiki.<br>
<br>
/_STEP 2:_/ discuss and add the content that's missing from the<br>
'I-am-a-contributor' position.<br>
<br>
*Problems to Discuss*<br>
<br>
Lets answer the main questions and plan the future basing on the<br>
decision made:<br>
<br>
1. The first and the most important question is:<br>
<br>
*Documentation Contributor Guide: to be or not to be? *<br>
</blockquote>
<br>
I'd love to see this - but only as long as there's a small team dedicated to move everything from the wiki.<br>
<br>
I also like to see a spec for this effort to design what we want.<br></blockquote><div><br><br></div><div>I am willing to take care of this after we discuss and arrive at a consensus about the guide scopes, creating/publishing procedure and deadlines.<br><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
2. Where is the most appropriate location for it?<br>
<br>
I agree that <a href="http://docs.openstack.org/infra" rel="noreferrer" target="_blank">http://docs.openstack.org/infra</a> is the best place, but<br>
before taking any steps in this direction, we should thoroughly discuss<br>
what kind of content this should include with the its owner, and find a<br>
compromise. Jeremy, did I understand your point right?<br>
</blockquote>
<br>
We can easily publish anywhere where it fits, the URL is for me just cosmetics. I don't think that /infra is the best fit.<br>
<br>
Looking at your question, the question becomes more: Do we move some parts to infra-manual (<a href="http://docs.openstack.org/infra/manual" rel="noreferrer" target="_blank">docs.openstack.org/infra/manual</a>) and some to our own place and link between the two? Or what's the relationship between what you propose and infra-manual.<br></blockquote><div><br><br></div><div>No, I am against splitting the contributor-related information. I am for the Contributor Guide (not a kind of a guide related to the writing style only).<br></div><div>If you know the better place for it, lets discuss as I am probably not experienced enough in this question.<br></div><div><br> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Do we want to do this work as part of an existing repository - docs-specs and openstack-manuals come to mind for that - or create a new one?<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Thank you all for reading this up to the end, and for any feedback on<br>
the matter!<br>
</blockquote>
<br>
Thanks, Olga for moving this forward!<br>
<br>
Andreas<br>
<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Olga.<br>
<br>
<br>
<br>
On Thu, May 28, 2015 at 10:03 PM, Jeremy Stanley <<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a><br>
<mailto:<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a>>> wrote:<span class=""><br>
<br>
On 2015-05-28 19:24:15 +0200 (+0200), Christian Berendt wrote:<br>
[...]<br></span>
> If we confirm to move the content into the already existing<br>
> developers guide what do we have to do to proceed?<span class=""><br>
<br>
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>
<br></span>
> 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>
I'm happy to respond here, but yes you might reach more of the<br>
infra-manual authors on the -dev or -infra MLs.<span class=""><br>
--<br>
Jeremy Stanley<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">OpenStack-docs@lists.openstack.org</a><br></span>
<mailto:<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">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>
<br>
<br>
<br>
<br>
--<br>
Best regards,<br>
Olga<br>
<br>
Technical Writer<br>
skype: gusarenko.olga<span class=""><br>
<br>
<br>
<br>
_______________________________________________<br>
OpenStack-docs mailing list<br>
<a href="mailto:OpenStack-docs@lists.openstack.org" target="_blank">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>
<br>
</span></blockquote><span class=""><font color="#888888">
<br>
<br>
-- <br>
Andreas Jaeger aj@{<a href="http://suse.com" rel="noreferrer" target="_blank">suse.com</a>,<a href="http://opensuse.org" rel="noreferrer" target="_blank">opensuse.org</a>} Twitter/Identica: jaegerandi<br>
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany<br>
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,<br>
HRB 21284 (AG Nürnberg)<br>
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126<br>
<br>
</font></span></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></div></div>