Open Stack

On Wed, Oct 30, 2013 at 8:02 AM, Lorin Hochstein
<lorin at nimbisservices.com>wrote:

> Hi Anne:
>
> Gotcha. Has there been any discussion about what to do with the
> python-*client sites? We have a bunch of them, and they aren't very
> consistent in quality (or even css theming!). I don't even know what
> triggers an update to these, if it's on commit to the client repository or
> only when new point versions are released to pypi, or some other event.
>

I'm fairly certain the source lives in doc/source in each repo:

https://github.com/openstack/python-novaclient/tree/master/doc/source

If you look at
https://github.com/openstack-infra/config/blob/master/modules/openstack_project/files/jenkins_job_builder/config/openstack-publish-jobs.yamlyou
see the jobs to build those. Pretty sure they're triggered on commit.
It's just that no one has done real doc work on those. It'd be great if you
are up for it.


>
> They're potentially a good place to serve as SDK reference because of
> Sphinx auto-doc. I'm interested in working on cleaning these up, maybe
> using the keystoneclient site as the reference since it's OpenStack themed <
> http://docs.openstack.org/developer/python-keystoneclient/>.
>
> Is this going to be discussed at the SDK session at the summit? (Alas I
> won't be there).
>

I'll make sure we do, it's a recurring theme release after release that
those sites are mostly ignored. Thanks for bringing it up.

I also have a hunch (seriously, just a guess) that for a long while people
were just hoping that openstackclient would take over and the individual
docs wouldn't have to be maintained? What do you think about that
possibility?

Anne


>
>
> We have a whole bunch of sites:
>
> * http://docs.openstack.org/developer/python-novaclient/
> * http://docs.openstack.org/developer/python-keystoneclient/
> * http://docs.openstack.org/developer/python-cinderclient/
> * http://docs.openstack.org/developer/python-swiftclient/
> * http://docs.openstack.org/developer/python-glanceclient/
> * http://docs.openstack.org/developer/python-neutronclient/
> * http://docs.openstack.org/developer/python-heatclient/
> * http://docs.openstack.org/developer/python-ceilometerclient/
> * http://docs.openstack.org/developer/python-openstackclient/
>
>
> Lorin
>
>
> On Wed, Oct 30, 2013 at 8:51 AM, Anne Gentle <
> annegentle at justwriteclick.com> wrote:
>
>>
>>
>>
>> On Tue, Oct 29, 2013 at 9:06 PM, Lorin Hochstein <
>> lorin at nimbisservices.com> wrote:
>>
>>> All:
>>>
>>> For the RST conversion, are you also going to be targeting the
>>> python-*client documentation that currently exists (e.g.,
>>> python-novaclient, python-swiftclient, ...)?
>>>
>>>
>> Hi Lorin,
>>
>> Only hand-edited RST files from the 6 core projects are in the scope as
>> far as I know.
>>
>> Anne
>>
>>
>>> Lorin
>>>
>>>
>>> On Tue, Oct 29, 2013 at 5:22 PM, Anne Gentle <
>>> annegentle at justwriteclick.com> wrote:
>>>
>>>> Hi again everyone,
>>>>
>>>> Nermina, Sean and I spoke today and Sean's going to modify his
>>>> blueprint and start with a patch that contains the conversion tool plus
>>>> just the RST files for cinder, to be placed in doc/training-guide. He'll
>>>> show the placement in the associates guide so reviewers can see the
>>>> end-goal as well as the steps prior to the training guide update. Nermina
>>>> can take a look at what could be incorporated into other guides.
>>>>
>>>> I hope this is a good step forward to get some proof of concept content
>>>> in there so reviewers can take a look and offer suggestions.
>>>>
>>>> Thanks,
>>>> Anne
>>>>
>>>>
>>>> On Mon, Oct 28, 2013 at 7:45 PM, Nermina Miller <
>>>> nerminamiller at gmail.com> wrote:
>>>>
>>>>> Hello everyone,
>>>>>
>>>>> I've reviewed the training docs and spoke to Sean today, and here is a
>>>>> proposed solution for inclusion of the devref files converted from rst:
>>>>>
>>>>> *Immediate Steps/First Patch*
>>>>> - Submit the Associates Guide with xi:inclusions of the 30 relevant
>>>>> devref files (and appropriate updated xi:includes from the other guides)
>>>>> - Add the entire batch of the devref files to the Common folder
>>>>> (subfolder Training) so the files can be made available to the other guides
>>>>> in the long term. (Why all? Because the py script updates and converts them
>>>>> ALL at the same time. You may already know this but it helps to explain the
>>>>> need for such a large batch.)
>>>>>
>>>>> *NOTE:* Andreas, Sean may ask you for help to figure out the best
>>>>> commit procedure considering that the training guides may need to be made
>>>>> available for other releases besides Havana. (I've shared the latest
>>>>> backporting steps with Sean.)
>>>>>
>>>>> *IMPORTANT:* Hold off on the editing of rst converts until Sean's
>>>>> team publishes an appropriate procedure for that. All of the devref xml
>>>>> files have to be edited in the native rst format and then automatically
>>>>> converted with the script that will be stored in Common. Once the guide is
>>>>> merged, you can begin making comments and editing the files using the said
>>>>> procedure. (Sean said he would add it to the How To wiki.) Understand that
>>>>> this is a work in progress that needs the community's feedback through bug
>>>>> logs and fixes. That also means it would be incredibly helpful to add the
>>>>> training guides to the OpenStack docs index along with Disqus and Launchpad
>>>>> links.
>>>>>
>>>>> *Further Steps*
>>>>> - Add each of the remaining training guides with the appropriate
>>>>> xi:includes to the devref files in Common
>>>>> - Transition to the xml format so a wider audience can edit the files
>>>>> and for easier updates (and to eliminate the need for conversion). Also,
>>>>> align those docs with the OpenStack docs file naming and other conventions.
>>>>>
>>>>> Sean is planning to submit the first patch tomorrow. It would be great
>>>>> to have at least one guide to showcase in Hong Kong, and I believe we need
>>>>> to help Sean make that happen so the training group can begin receiving
>>>>> feedback and growing their guides live.
>>>>>
>>>>> Thank you, Sean! Please correct or add to any of the information
>>>>> listed here. And, thank you, all for considering these points.
>>>>>
>>>>> Nermina
>>>>>
>>>>>
>>>>> On Mon, Oct 21, 2013 at 8:52 PM, Nermina Miller <
>>>>> nerminamiller at gmail.com> wrote:
>>>>>
>>>>>> No problem, Anne. Colin, if this is the missing batch, where is the
>>>>>> rest of the guide? Also, do you have a blueprint or a proposed ToC I can
>>>>>> take a look at? Please brief me on the history of training docs a little.
>>>>>> Thanks much! - Nermina
>>>>>>
>>>>>>
>>>>>> On Mon, Oct 21, 2013 at 7:52 PM, Anne Gentle <
>>>>>> annegentle at justwriteclick.com> wrote:
>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> On Mon, Oct 21, 2013 at 6:43 PM, Nermina Miller <
>>>>>>> nerminamiller at gmail.com> wrote:
>>>>>>>
>>>>>>>> Anne and Colin, I'd be happy to help with content management and
>>>>>>>> migration. -Nermina
>>>>>>>>
>>>>>>>>
>>>>>>> Awesome, Nermina! I think you'll find a list of content they found
>>>>>>> missing at
>>>>>>> https://review.openstack.org/#/c/50509/1
>>>>>>>
>>>>>>> And someone do tell me if I'm being crazy in taking on more
>>>>>>> conceptual doc that we might not be able to maintain. I trust you all!
>>>>>>>
>>>>>>> Thanks,
>>>>>>>
>>>>>>> Anne
>>>>>>>
>>>>>>>
>>>>>>>> On Monday, October 21, 2013, Anne Gentle wrote:
>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Thu, Oct 10, 2013 at 12:02 PM, Colin McNamara <colin at 2cups.com>wrote:
>>>>>>>>>
>>>>>>>>>> I absolutely believe that the appropriate role is to improve the
>>>>>>>>>> source documentation. Right now I'm just riding a find line between
>>>>>>>>>> improving and duplicating. My focus has been on getting the structure of
>>>>>>>>>> training-guides through included content, and then when we get to our alpha
>>>>>>>>>> to focus on improving the referenced content.
>>>>>>>>>>
>>>>>>>>>> A direct example of that would on the administrative section that
>>>>>>>>>> references the user-guide content. There are items in there that could
>>>>>>>>>> benefit from visual representation of the steps noted. My goal is to get
>>>>>>>>>> the included content roughed out in the training-guide, and then engage the
>>>>>>>>>> user group contributors that we have been building to do things like create
>>>>>>>>>> visual representations of configuration steps that are unclear.
>>>>>>>>>>
>>>>>>>>>> So, to be very clear. My goals are to improve the source
>>>>>>>>>> documentation. My suggested method is to focus on xi:inclusion as much as
>>>>>>>>>> possible within training-guides. This drives the improvement in content to
>>>>>>>>>> the sources that are referenced, vs creating yet another external
>>>>>>>>>> operations guide that won't be able to map to the six month release
>>>>>>>>>> schedule.
>>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> Circling back to take a closer look now that the release is out.
>>>>>>>>>
>>>>>>>>> I like your main goal of improving the source documentation. But
>>>>>>>>> RST documentation isn't great source since it can't be xi:included, it gets
>>>>>>>>> hung up in reviews for a long time, it's not well maintained, I'm just not
>>>>>>>>> sure you want to use it as your source. I'm trying to help you avoid a
>>>>>>>>> pitfall here. :)
>>>>>>>>>
>>>>>>>>> So far the data shows that the dev docs are less maintained, when
>>>>>>>>> we bring them in to openstack-manuals they tend to improve at a faster
>>>>>>>>> rate. I could go through your review a file at a time and tell you where
>>>>>>>>> the info should go, but I can't make it a priority myself right now. Is
>>>>>>>>> there anyone else you can identify to help you with content placement? I'd
>>>>>>>>> also recommend a file at a time to help reviewers review your patches. Or a
>>>>>>>>> project at a time. Some way of helping reviewers see the whole deliverable
>>>>>>>>> will help reviewers.
>>>>>>>>>
>>>>>>>>> Anyone else want to add to the discussion? Feel free to add
>>>>>>>>> RST-as-source to tomorrow's doc team meeting agenda at
>>>>>>>>> https://wiki.openstack.org/wiki/Meetings/DocTeamMeeting#Agenda_for_next_meeting
>>>>>>>>> .
>>>>>>>>>
>>>>>>>>> Anne
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>    Regards,
>>>>>>>>>
>>>>>>>>> Colin
>>>>>>>>> *Colin McNamara*
>>>>>>>>> People | Process | Technology
>>>>>>>>> --------------------------------------------
>>>>>>>>> *Mobile*:  858-208-8105
>>>>>>>>> *Twitter: *@colinmcnamara <http://www.twitter.com/colinmcnamara>
>>>>>>>>> *Linkedin*: www. <http://www.linkedin.com/colinmcnamara>
>>>>>>>>> linkedin.com/colinmcnamara <http://www.linkedin.com/colinmcnamara>
>>>>>>>>> *Blog*: www.colinmcnamara.com
>>>>>>>>> *Email*: colin at 2cups.com
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Oct 10, 2013, at 9:35 AM, Anne Gentle <
>>>>>>>>> annegentle at justwriteclick.com> wrote:
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> On Thu, Oct 10, 2013 at 11:06 AM, Colin McNamara <
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>>
>>>>>>>>> --
>>>>>>>>> Anne Gentle
>>>>>>>>> annegentle at justwriteclick.com
>>>>>>>>>
>>>>>>>>
>>>>>>>>
>>>>>>>> --
>>>>>>>> Thank you!
>>>>>>>>
>>>>>>>> Nermina Miller
>>>>>>>> Tech Writer and Editor
>>>>>>>>
>>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> --
>>>>>>> Anne Gentle
>>>>>>> annegentle at justwriteclick.com
>>>>>>>
>>>>>>
>>>>>>
>>>>>>
>>>>>> --
>>>>>> Thank you!
>>>>>>
>>>>>> Nermina Miller
>>>>>> Tech Writer and Editor
>>>>>>
>>>>>
>>>>>
>>>>>
>>>>> --
>>>>> Thank you!
>>>>>
>>>>> Nermina Miller
>>>>> Tech Writer and Editor
>>>>>
>>>>
>>>>
>>>>
>>>> --
>>>> Anne Gentle
>>>> annegentle at justwriteclick.com
>>>>
>>>> _______________________________________________
>>>> Openstack-docs mailing list
>>>> Openstack-docs at lists.openstack.org
>>>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>>>>
>>>>
>>>
>>>
>>> --
>>> Lorin Hochstein
>>> Lead Architect - Cloud Services
>>> Nimbis Services, Inc.
>>> www.nimbisservices.com
>>>
>>
>>
>>
>> --
>> Anne Gentle
>> annegentle at justwriteclick.com
>>
>
>
>
> --
> Lorin Hochstein
> Lead Architect - Cloud Services
> Nimbis Services, Inc.
> www.nimbisservices.com
>



-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20131030/1a29574a/attachment-0001.html>