Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Lana Brindley]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 08/03/16 02:09, Hayes, Graham wrote:
> On 07/03/2016 16:00, Matt Kassawara wrote:
>> Snipping a lot, because I'm particularly interested in one comment...
>>
>>
>> I agree that many developers (especially developers of those groups
>> new to the big tent) seem to think that they need to be on the top
>> level docs.openstack.org , without
>> necessarily understanding that docs.openstack.org/developer
>>  is usually the more
>> appropriate place, at  least to begin with. This should probably be
>> made more explicit both in the Infra Manual, plus anywhere that
>> Foundation is discussing big tent inclusion.
>>
>>
>> We tell operators and users to look at the documentation on
>> docs.openstack.org  because the documentation
>> in /developer is aimed at developers and often lacks polish. Now we're
>> telling developers to put operator/user documentation into /developer?
> 
> To follow up on that - the Foundations "Project Navigator" has one of
> the maturity requirements as "Is there an install guide for this
> project guide (at docs.openstack.org)?"
> 
> If this is required, how can projects get content in to this.
> 
> I went looking about 6 months ago for the information that Stephen
> asked for to update (create) our docs, but couldn't find it.
> 

To try and answer both questions in one reply: The developer documentation 
should live on /developer, with config options automatically picked up for the 
Config Reference where appropriate. If you are new to the big tent, then you 
should also use /developer to create and polish your user documentation. This 
is enough to be considered 'official' according to the Project Navigator. Once 
you have a good amount of quality content, then please feel free to open a 
conversation with docs about inclusion in the top level.

The main reason we do it this way is because writing docs is a very manual, 
labour-intensive task, and the docs team is small. We already have a lot of 
content that we maintain and a lot of people throwing things over the wall to 
us. We simply cannot have every big tent project present in the Install Guide.

Hope that helps clear things up.

Lana

- -- 
Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-BEGIN PGP SIGNATURE-
Version: GnuPG v2
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQEcBAEBCAAGBQJW3gf/AAoJELppzVb4+KUygvgH/3CLosJOZQ4HOGzZ6gyESAip
7gxKSNRaN9LTVXGUFMpSwppDMPguM2X78bpQB1cSa6A20mvRHbHKVFtio/virn1l
05R0iWRR5I157ggfVFA8P+tLeVONVTQi0Sa9W/L6GU/Ihr7mplVptYz5tpipmJy9
RYwa3LlOCF1qMQogOdNcv+5Tg2ci6Sqn03xw43jN18iC2dAtJVZJxmjO760mJ9h9
9uLDpb8GOvrCNvM4hdiWoZlEIbYpViaZGcYqQElml1RqZOmzswC1GOrquGIENkTl
eClj7UFUUji0/6WqeoDjSq/60NzT/i+IYvBd0bFDPgmn2kZLt67xCgoyfrj1Cik=
=AfBL
-END PGP SIGNATURE-

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

Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Hayes, Graham]

On 07/03/2016 16:00, Matt Kassawara wrote:
> Snipping a lot, because I'm particularly interested in one comment...
>
>
> I agree that many developers (especially developers of those groups
> new to the big tent) seem to think that they need to be on the top
> level docs.openstack.org , without
> necessarily understanding that docs.openstack.org/developer
>  is usually the more
> appropriate place, at  least to begin with. This should probably be
> made more explicit both in the Infra Manual, plus anywhere that
> Foundation is discussing big tent inclusion.
>
>
> We tell operators and users to look at the documentation on
> docs.openstack.org  because the documentation
> in /developer is aimed at developers and often lacks polish. Now we're
> telling developers to put operator/user documentation into /developer?

To follow up on that - the Foundations "Project Navigator" has one of
the maturity requirements as "Is there an install guide for this
project guide (at docs.openstack.org)?"

If this is required, how can projects get content in to this.

I went looking about 6 months ago for the information that Stephen
asked for to update (create) our docs, but couldn't find it.

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

Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Matt Kassawara]

Snipping a lot, because I'm particularly interested in one comment...


> I agree that many developers (especially developers of those groups new to
> the big tent) seem to think that they need to be on the top level
> docs.openstack.org, without necessarily understanding that
> docs.openstack.org/developer is usually the more appropriate place, at
> least to begin with. This should probably be made more explicit both in the
> Infra Manual, plus anywhere that Foundation is discussing big tent
> inclusion.


We tell operators and users to look at the documentation on
docs.openstack.org because the documentation in /developer is aimed at
developers and often lacks polish. Now we're telling developers to put
operator/user documentation into /developer?
__
OpenStack Development Mailing List (not for usage questions)
Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Lana Brindley]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

(Snipping throughout)

On 04/03/16 15:39, Stephen Balukoff wrote:
> Hello Lana!
> 
> Thank you for your prompt reply--  I found it extremely helpful!  Comments
> inline:
> 



>>> Anyway, so then I went to try to figure out how I get this auto-generated
>>> output updated, and haven't found much (ha!) documented on the process...
>>> when I sought help from Sam-I-Am, I was told that these essentially get
>>> generated once per release by "somebody." So...  I'm done, right?
>>
>> That 'somebody', to be more specific, is the speciality team in charge of
>> the book in question. We also do a full refresh of the scripts before each
>> release.
>>
>>
> Cool! Is that process documented anywhere? Or better yet, is there a way
> for developers to do a "check experimental" or similar operation on any
> given patch so we can see what the manual will look like after our API /
> CLI updates (presumably in said patch)?
> 

To be honest, this is seriously underdocumented, and we're well aware of that. 
I do know that a few people are working on rectifying that situation, and I 
believe that Brian Moss will have a patch up soon to add some more info to the 
Contributor's Guide. Docs infra (like so much other infra) has been built up 
over time, and it's a big beast to untangle and document. 

I'm not aware of a tool to check for automated docs updates, though, sorry.



>> Depending on the feature and project in question, I would usually
>> recommend you add it to the appropriate documentation in your project repo.
>> These are then published to
>> http://docs.openstack.org/developer/[yourproject] and are considered
>> official OpenStack documentation.
>>
>> If you want it added to the broader OpenStack documentation (the top level
>> on the docs.openstack.org), then I suggest you open a bug, wait for a
>> docs person to triage it (we can help advise on book/chapter, etc), and
>> then create a patch against the book in the same way as you do for your
>> project. If you don't want to write it yourself, that's fine. Open the bug,
>> give as much detail as you can, and we'll take it from there.
>>
>>
> Aah--  so I knew that the Octavia documentation we've committed thus far
> showed up that way but I'd been given the impression that we were doing the
> wrong thing: That it was generally not considered a good thing to have your
> documentation live in your own custom non-openstack-manual space and that
> you should instead work to get all of it moved into the openstack manual.

Not at all, docs.openstack.org/developer is considered official, and is 
absolutely the right place for developer documentation :)

> 
> In any case it's good to know about how you prefer people contribute
> changes to the manual: I expected y'all to want full editorial control over
> everything the goes into the manual, but I didn't know you'd just go write
> excerpts yourself on features that developers add and then open
> documentation bug reports for. That sounds like a lot of work for you!
> 

It's what tech writers do :P




>>
>> There's not a lot of content here to share. You commit docs in exactly the
>> same way as you commit code. If you already have the skills to commit code
>> to an OpenStack project, then you know everything you need to know to
>> commit to docs.
>>
> 
> ...except for the stuff that's in there right now that's auto-generated. :)
> I wonder if there's a better way to communicate that developers generally
> won't have to worry about updating API / CLI references manually as this is
> all auto-generated... other than having been here long enough to know
> that's the case. (FWIW, I dislike relying on tribal knowledge...)
> 

This is mentioned explicitly in the Contributor Guide: 
http://docs.openstack.org/contributor-guide/docs-builds.html I do acknowledge, 
though, that we don't go into detail on how the automation works. The best we 
really have at the moment is this: 
http://git.openstack.org/cgit/openstack/openstack-doc-tools/tree/autogenerate_config_docs/README.rst
 which isn't a great solution. As I mentioned earlier, we're working on it. 
Happy to take suggestions on where you think we should have more content around 
this.




> 
> Aah-- you're right that a good portion of this is already documented there.
> Sorry-- I looked through the guide but didn't see what I was after in a lot
> of it.
> 
> I guess the piece that was missing for me here was an opinionated guideline
> on where documentation should go that is not necessarily appropriate for
> the general openstack manual. You already told me above it should go in
> project-specific documentation repositories, but perhaps it would be
> helpful to mention something about that in this contributor guide? More on
> this later...
> 

I agree that this probably isn't explicit in the Contributor Guide. I'll go 
ahead and do something about that this week.

It is mentioned in the Infra Guide here: 

Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Stephen Balukoff]

Hello Lana!

Thank you for your prompt reply--  I found it extremely helpful!  Comments
inline:


> > So in the intervening days I've been going through the openstack-manuals,
> > openstack-doc-tools, and other repositories, trying to figure out where I
> > make my edits. I found both the CLI and API reference in the
> > openstack-manuals repository... but when I went to edit these files, I
> > noticed that there's a comment at the top stating they are auto-generated
> > and shouldn't be edited? It seemed odd to me that the results of
> something
> > auto-generated should be checked into a git repository instead of the
> > configuration which creates the auto-generated output... but it's not my
> > project, right?
>
> Believe me, we know. At the moment, this is the best we can do with what
> we have to work with.
>

Yep! I get it.



> > Anyway, so then I went to try to figure out how I get this auto-generated
> > output updated, and haven't found much (ha!) documented on the process...
> > when I sought help from Sam-I-Am, I was told that these essentially get
> > generated once per release by "somebody." So...  I'm done, right?
>
> That 'somebody', to be more specific, is the speciality team in charge of
> the book in question. We also do a full refresh of the scripts before each
> release.
>
>
Cool! Is that process documented anywhere? Or better yet, is there a way
for developers to do a "check experimental" or similar operation on any
given patch so we can see what the manual will look like after our API /
CLI updates (presumably in said patch)?



> > Well... I'm not so sure. Yes, if the CLI and API documentation gets
> > auto-generated from the right sources, we should be good to go on that
> > front, but how can I be sure the automated process is pulling this
> > information from the right place? Shouldn't there be some kind of
> > continuous integration or jenkins check which tests this that I can look
> > at? (And if such a thing exists, how am I supposed to find out about it?)
> >
> > Also, the new feature I've added is somewhat involved, and it could
> > probably use another document describing its intended use beyond the CLI
> /
> > API ref. Heck, we already created on in the OpenStack wiki... but I'm
> also
> > being told that we're trying to not rely on the wiki as much, per se, and
> > that anything in the wiki really ought to be moved into the "official"
> > documentation canon.
>
> Depending on the feature and project in question, I would usually
> recommend you add it to the appropriate documentation in your project repo.
> These are then published to
> http://docs.openstack.org/developer/[yourproject] and are considered
> official OpenStack documentation.
>
> If you want it added to the broader OpenStack documentation (the top level
> on the docs.openstack.org), then I suggest you open a bug, wait for a
> docs person to triage it (we can help advise on book/chapter, etc), and
> then create a patch against the book in the same way as you do for your
> project. If you don't want to write it yourself, that's fine. Open the bug,
> give as much detail as you can, and we'll take it from there.
>
>
Aah--  so I knew that the Octavia documentation we've committed thus far
showed up that way but I'd been given the impression that we were doing the
wrong thing: That it was generally not considered a good thing to have your
documentation live in your own custom non-openstack-manual space and that
you should instead work to get all of it moved into the openstack manual.

In any case it's good to know about how you prefer people contribute
changes to the manual: I expected y'all to want full editorial control over
everything the goes into the manual, but I didn't know you'd just go write
excerpts yourself on features that developers add and then open
documentation bug reports for. That sounds like a lot of work for you!



> >
> > So I'm at a loss. I'm a big fan of documentation as a communication
> > tool, and I'm an experienced OpenStack developer, but when I look in the
> > manual for how to contribute to the OpenStack documentation, I find a
> guide
> > that wants to walk me through setting up gerrit... and very little
> targeted
> > toward someone who already knows that, but just needs to know the actual
> > process for updating the manual (and which part of the manual should be
> > updated).
>
> There's not a lot of content here to share. You commit docs in exactly the
> same way as you commit code. If you already have the skills to commit code
> to an OpenStack project, then you know everything you need to know to
> commit to docs.
>

...except for the stuff that's in there right now that's auto-generated. :)
I wonder if there's a better way to communicate that developers generally
won't have to worry about updating API / CLI references manually as this is
all auto-generated... other than having been here long enough to know
that's the case. (FWIW, I dislike relying on tribal knowledge...)

Re: [openstack-dev] [OpenStack-docs] Fwd: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor documentation best-practices and how-tos

[Lana Brindley]

-BEGIN PGP SIGNED MESSAGE-
Hash: SHA256

On 04/03/16 11:41, Stephen Balukoff wrote:
> Hah! Didn't realize that 'docs' had its own mailing list. XD Anyway, please
> see the e-mail below:

Thanks for drawing this to our attention.

> 
> -- Forwarded message --
> From: Stephen Balukoff 
> Date: Thu, Mar 3, 2016 at 4:56 PM
> Subject: [Neutron][LBaaS][Octavia][Docs] Need experienced contributor
> documentation best-practices and how-tos
> To: "OpenStack Development Mailing List (not for usage questions)" <
> openstack-dev@lists.openstack.org>
> 
> 
> Hello!
> 
> I have a problem I'm hoping someone can help with: I have gone through the
> task of completing a shiny new feature for an openstack project, and now
> I'm trying to figure out how to get that last all-important documentation
> step done so that people will know about this new feature and use it. But
> I'm having no luck figuring out how I actually go about doing this...
> 
> This started when I was told that in order to consider the feature
> "complete," I needed to make sure that it was documented in the openstack
> official documentation. I wholeheartedly agree with this: If it's not
> documented, very few people will know about it, let alone use it. And few
> things make an open-source contributor more sad than the idea that the work
> they've spent months or years completing isn't getting used.
> 
> So... No problem! I'm an experienced OpenStack developer, and I just spent
> months getting this major new feature through my project's gauntlet of an
> approval process. How hard could documenting it be, right?
> 
> So in the intervening days I've been going through the openstack-manuals,
> openstack-doc-tools, and other repositories, trying to figure out where I
> make my edits. I found both the CLI and API reference in the
> openstack-manuals repository... but when I went to edit these files, I
> noticed that there's a comment at the top stating they are auto-generated
> and shouldn't be edited? It seemed odd to me that the results of something
> auto-generated should be checked into a git repository instead of the
> configuration which creates the auto-generated output... but it's not my
> project, right?

Believe me, we know. At the moment, this is the best we can do with what we 
have to work with.

> 
> Anyway, so then I went to try to figure out how I get this auto-generated
> output updated, and haven't found much (ha!) documented on the process...
> when I sought help from Sam-I-Am, I was told that these essentially get
> generated once per release by "somebody." So...  I'm done, right?

That 'somebody', to be more specific, is the speciality team in charge of the 
book in question. We also do a full refresh of the scripts before each release.

> 
> Well... I'm not so sure. Yes, if the CLI and API documentation gets
> auto-generated from the right sources, we should be good to go on that
> front, but how can I be sure the automated process is pulling this
> information from the right place? Shouldn't there be some kind of
> continuous integration or jenkins check which tests this that I can look
> at? (And if such a thing exists, how am I supposed to find out about it?)
> 
> Also, the new feature I've added is somewhat involved, and it could
> probably use another document describing its intended use beyond the CLI /
> API ref. Heck, we already created on in the OpenStack wiki... but I'm also
> being told that we're trying to not rely on the wiki as much, per se, and
> that anything in the wiki really ought to be moved into the "official"
> documentation canon.

Depending on the feature and project in question, I would usually recommend you 
add it to the appropriate documentation in your project repo. These are then 
published to http://docs.openstack.org/developer/[yourproject] and are 
considered official OpenStack documentation.

If you want it added to the broader OpenStack documentation (the top level on 
the docs.openstack.org), then I suggest you open a bug, wait for a docs person 
to triage it (we can help advise on book/chapter, etc), and then create a patch 
against the book in the same way as you do for your project. If you don't want 
to write it yourself, that's fine. Open the bug, give as much detail as you 
can, and we'll take it from there.

> 
> So I'm at a loss. I'm a big fan of documentation as a communication
> tool, and I'm an experienced OpenStack developer, but when I look in the
> manual for how to contribute to the OpenStack documentation, I find a guide
> that wants to walk me through setting up gerrit... and very little targeted
> toward someone who already knows that, but just needs to know the actual
> process for updating the manual (and which part of the manual should be
> updated).

There's not a lot of content here to share. You commit docs in exactly the same 
way as you commit code. If you already have the skills to commit code to an 
OpenStack project,