<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office" xmlns:w="urn:schemas-microsoft-com:office:word" xmlns:m="http://schemas.microsoft.com/office/2004/12/omml" xmlns="http://www.w3.org/TR/REC-html40"><head><meta http-equiv=Content-Type content="text/html; charset=utf-8"><meta name=Generator content="Microsoft Word 15 (filtered medium)"><style><!--
/* Font Definitions */
@font-face
{font-family:Wingdings;
panose-1:5 0 0 0 0 0 0 0 0 0;}
@font-face
{font-family:"MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
@font-face
{font-family:"Cambria Math";
panose-1:2 4 5 3 5 4 6 3 2 4;}
@font-face
{font-family:Calibri;
panose-1:2 15 5 2 2 2 4 3 2 4;}
@font-face
{font-family:"\@MS Mincho";
panose-1:2 2 6 9 4 2 5 8 3 4;}
/* Style Definitions */
p.MsoNormal, li.MsoNormal, div.MsoNormal
{margin:0in;
margin-bottom:.0001pt;
font-size:12.0pt;
font-family:"Times New Roman",serif;}
a:link, span.MsoHyperlink
{mso-style-priority:99;
color:blue;
text-decoration:underline;}
a:visited, span.MsoHyperlinkFollowed
{mso-style-priority:99;
color:purple;
text-decoration:underline;}
p
{mso-style-priority:99;
mso-margin-top-alt:auto;
margin-right:0in;
mso-margin-bottom-alt:auto;
margin-left:0in;
font-size:12.0pt;
font-family:"Times New Roman",serif;}
span.hoenzb
{mso-style-name:hoenzb;}
span.EmailStyle19
{mso-style-type:personal-reply;
font-family:"Calibri",sans-serif;
color:#1F497D;}
.MsoChpDefault
{mso-style-type:export-only;
font-family:"Calibri",sans-serif;}
@page WordSection1
{size:8.5in 11.0in;
margin:1.0in 1.0in 1.0in 1.0in;}
div.WordSection1
{page:WordSection1;}
/* List Definitions */
@list l0
{mso-list-id:2054190493;
mso-list-template-ids:-1074334492;}
@list l0:level1
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:.5in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Symbol;}
@list l0:level2
{mso-level-number-format:bullet;
mso-level-text:o;
mso-level-tab-stop:1.0in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:"Courier New";
mso-bidi-font-family:"Times New Roman";}
@list l0:level3
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:1.5in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level4
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:2.0in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level5
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:2.5in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level6
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:3.0in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level7
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:3.5in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level8
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:4.0in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
@list l0:level9
{mso-level-number-format:bullet;
mso-level-text:;
mso-level-tab-stop:4.5in;
mso-level-number-position:left;
text-indent:-.25in;
mso-ansi-font-size:10.0pt;
font-family:Wingdings;}
ol
{margin-bottom:0in;}
ul
{margin-bottom:0in;}
--></style><!--[if gte mso 9]><xml>
<o:shapedefaults v:ext="edit" spidmax="1026" />
</xml><![endif]--><!--[if gte mso 9]><xml>
<o:shapelayout v:ext="edit">
<o:idmap v:ext="edit" data="1" />
</o:shapelayout></xml><![endif]--></head><body lang=EN-US link=blue vlink=purple><div class=WordSection1><p style='margin-bottom:0in;margin-bottom:.0001pt'>1. The first and the most important question is:<o:p></o:p></p><p style='mso-margin-top-alt:5.0pt;margin-right:0in;margin-bottom:0in;margin-left:30.0pt;margin-bottom:.0001pt'><b>Documentation Contributor Guide: to be or not to be? <o:p></o:p></b></p><p style='mso-margin-top-alt:5.0pt;margin-right:0in;margin-bottom:0in;margin-left:30.0pt;margin-bottom:.0001pt'><b><span style='font-size:14.0pt;font-family:"Calibri",sans-serif;color:#1F497D'>YES!</span></b><span style='font-size:14.0pt;font-family:"Calibri",sans-serif;color:#1F497D'> </span><span style='font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D'><br>By an occasional contributor who still often wonders what’s the right procedure.<o:p></o:p></span></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>2. Where is the most appropriate location for it?<o:p></o:p></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal style='margin-left:.5in'><span style='font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D'>I don’t mind, but I agree that the Wiki pages are or have become hard to read.<o:p></o:p></span></p><p class=MsoNormal><span style='font-size:11.0pt;font-family:"Calibri",sans-serif;color:#1F497D'><o:p> </o:p></span></p><p class=MsoNormal><b><span style='font-size:11.0pt;font-family:"Calibri",sans-serif'>From:</span></b><span style='font-size:11.0pt;font-family:"Calibri",sans-serif'> Olga Gusarenko [mailto:ogusarenko@mirantis.com] <br><b>Sent:</b> Wednesday, July 01, 2015 5:33 PM<br><b>To:</b> openstack-docs<br><b>Subject:</b> Re: [OpenStack-docs] move of documentation-related wiki content (was: Re: Wrapup - Liberty Design Summit)<o:p></o:p></span></p><p class=MsoNormal><o:p> </o:p></p><div><p style='margin-bottom:0in;margin-bottom:.0001pt'>Hi to everyone!<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>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 =)<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>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.<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'><b>Problem Description</b><o:p></o:p></p><p class=MsoNormal>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. <o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'><b>Proposed Solution</b><o:p></o:p></p><p class=MsoNormal>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: <o:p></o:p></p><ul type=disc><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'>Markup conventions<o:p></o:p></li><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'>Terminology and writing syntax conventions<o:p></o:p></li><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'>Screenshots and topologies conventions<o:p></o:p></li><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'>Documentation structure<o:p></o:p></li><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'>Gerrit workflow (HowTo)<o:p></o:p></li><li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;mso-list:l0 level1 lfo1'><i>anything else interesting to the community </i><o:p></o:p></li></ul><p style='margin-bottom:0in;margin-bottom:.0001pt'><b>What To Be Done</b><o:p></o:p></p><p class=MsoNormal>This task can be resolved in two steps: <o:p></o:p></p><p style='margin-bottom:.2in'><i><u>STEP 1:</u></i> moving the cleaned up content from wiki.<o:p></o:p></p><p style='margin-bottom:.2in'>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.<o:p></o:p></p><p style='margin-bottom:.2in'>Moving things around 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.<o:p></o:p></p><p style='margin-bottom:.2in'><i><u>STEP 2:</u></i> discuss and add the content that's missing from the 'I-am-a-contributor' position. <o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'><b>Problems to Discuss</b><o:p></o:p></p><p class=MsoNormal>Lets answer the main questions and plan the future basing on the decision made: <o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>1. The first and the most important question is:<o:p></o:p></p><p style='mso-margin-top-alt:5.0pt;margin-right:0in;margin-bottom:0in;margin-left:30.0pt;margin-bottom:.0001pt'><b>Documentation Contributor Guide: to be or not to be? </b><o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>2. Where is the most appropriate location for it?<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>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?<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>Thank you all for reading this up to the end, and for any feedback on the matter!<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'>Olga.<o:p></o:p></p><p style='margin-bottom:0in;margin-bottom:.0001pt'><o:p> </o:p></p><div><p class=MsoNormal><o:p> </o:p></p><div><p class=MsoNormal>On Thu, May 28, 2015 at 10:03 PM, Jeremy Stanley <<a href="mailto:fungi@yuggoth.org" target="_blank">fungi@yuggoth.org</a>> wrote:<o:p></o:p></p><blockquote style='border:none;border-left:solid #CCCCCC 1.0pt;padding:0in 0in 0in 6.0pt;margin-left:4.8pt;margin-right:0in'><p class=MsoNormal>On 2015-05-28 19:24:15 +0200 (+0200), Christian Berendt wrote:<br>[...]<br>> If we confirm to move the content into the already existing<br>> developers guide what do we have to do to proceed?<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>> 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.<br><span class=hoenzb><span style='color:#888888'>--</span></span><span style='color:#888888'><br><span class=hoenzb>Jeremy Stanley</span></span><o:p></o:p></p><div><div><p class=MsoNormal><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" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs</a><o:p></o:p></p></div></div></blockquote></div><p class=MsoNormal><br><br clear=all><br>-- <o:p></o:p></p><div><div><div><div><p class=MsoNormal>Best regards,<o:p></o:p></p></div><p class=MsoNormal style='margin-bottom:12.0pt'>Olga<o:p></o:p></p></div><p class=MsoNormal>Technical Writer<o:p></o:p></p><div><p class=MsoNormal>skype: gusarenko.olga <o:p></o:p></p></div><div><p class=MsoNormal><o:p> </o:p></p></div></div></div></div></div></div></body></html>