Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-07 Thread Christopher Yeoh
On Mon, 06 Oct 2014 11:24:30 +0200
Julien Danjou jul...@danjou.info wrote:

 On Sun, Oct 05 2014, Joshua Harlow wrote:
 
 I agree. I think we should have documentation be part of our policy to
 accept patches, just as we do with e.g. unit testing.
 
 Forcing people to write documentation along the patch will help
 writing better code, having a better understanding of what the patch
 does for reviewers, etc…
 

Agreed. And a lot of the confusion we get between what is documented to
happen and what is implemented in the code is due to different people
writing the documentation versus writing the code. And there has been
insufficient information (other than the code) left for people to write
accurate documentation.

For API docs I wonder if we should bringing more of that into the
project tree so we can enforce updating of documentation when the code
gets updated.

Chris


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Julien Danjou
On Sun, Oct 05 2014, Joshua Harlow wrote:

 IMHO, it should be up to the project itself to provide the resources to work
 *under the guidance* of the Docs team to write developer, end user and
 operator documentation. The Docs team members should be able to play an
 advisory role for new projects, helping them understand the automated doc
 processes, the way that common doc infrastructure works, and techniques for
 writing useful documentation consistent with other projects.

 Best,
 -jay

 Amen to that, it is our responsibility as developers to do this, for the 
 benefit
 of operators, developers, historians, ..., and users of openstack.

 And really it isn't that hard, you just have to devote some time to do it 
 (take
 1/2 of a day a week to devote to doing docs for your project). Eventually all
 those 1/2 of days add up to a decent set of usable docs for people using your
 project/library/other... If we had more people spending 1/2 or 1/4 a day a 
 week
 on improving docstrings, improving api/sphinx docs, improving diagrams we 
 would
 IMHO be in a much better position with respect to on-boarding new developers 
 and
 making it so that existing developers can understand prior architectural
 decisions (which is important for a variety of reasons, including but not
 limited to 'knowing what the reason for this code was' which can be useful
 when/if refactoring, knowing what the reason for this code was when adding new
 tests...).

 IMHO we shouldn't be leaning on the docs team to do our docs, just like we
 shouldn't be leaning on the TC to say what is 'blessed' or what isn't; these
 roles should be advisory and I think they should be primarily spreading best
 practices, and leading by example (which I believe makes good leadership and a
 healthy community).

I agree. I think we should have documentation be part of our policy to
accept patches, just as we do with e.g. unit testing.

Forcing people to write documentation along the patch will help writing
better code, having a better understanding of what the patch does for
reviewers, etc…

And will obviously benefit to users and operators.

-- 
Julien Danjou
;; Free Software hacker
;; http://julien.danjou.info


signature.asc
Description: PGP signature
___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Flavio Percoco
On 10/06/2014 11:24 AM, Julien Danjou wrote:
 On Sun, Oct 05 2014, Joshua Harlow wrote:
 
 IMHO, it should be up to the project itself to provide the resources to work
 *under the guidance* of the Docs team to write developer, end user and
 operator documentation. The Docs team members should be able to play an
 advisory role for new projects, helping them understand the automated doc
 processes, the way that common doc infrastructure works, and techniques for
 writing useful documentation consistent with other projects.

 Best,
 -jay

 Amen to that, it is our responsibility as developers to do this, for the 
 benefit
 of operators, developers, historians, ..., and users of openstack.

 And really it isn't that hard, you just have to devote some time to do it 
 (take
 1/2 of a day a week to devote to doing docs for your project). Eventually all
 those 1/2 of days add up to a decent set of usable docs for people using your
 project/library/other... If we had more people spending 1/2 or 1/4 a day a 
 week
 on improving docstrings, improving api/sphinx docs, improving diagrams we 
 would
 IMHO be in a much better position with respect to on-boarding new developers 
 and
 making it so that existing developers can understand prior architectural
 decisions (which is important for a variety of reasons, including but not
 limited to 'knowing what the reason for this code was' which can be useful
 when/if refactoring, knowing what the reason for this code was when adding 
 new
 tests...).

 IMHO we shouldn't be leaning on the docs team to do our docs, just like we
 shouldn't be leaning on the TC to say what is 'blessed' or what isn't; these
 roles should be advisory and I think they should be primarily spreading best
 practices, and leading by example (which I believe makes good leadership and 
 a
 healthy community).
 
 I agree. I think we should have documentation be part of our policy to
 accept patches, just as we do with e.g. unit testing.
 
 Forcing people to write documentation along the patch will help writing
 better code, having a better understanding of what the patch does for
 reviewers, etc…
 
 And will obviously benefit to users and operators.
 

This is a matter of making reviewers aware of this issue. As much as we
want to make it official, there's probably not a good/easy way to
enforce it besides asking reviewers to be nitpicky on these things.

By requesting docs on reviews, we'll encourage people to write docs
right away next time.

Cheers,
Flavio


-- 
@flaper87
Flavio Percoco

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Kenichi Oomichi

 -Original Message-
 From: Chris Friesen [mailto:chris.frie...@windriver.com]
 Sent: Saturday, October 04, 2014 1:27 PM
 To: openstack-dev@lists.openstack.org
 Subject: Re: [openstack-dev] [all][docs][tc] How to scale Documentation
 
 On 10/03/2014 07:50 PM, Anne Gentle wrote:
 
  Here's my current thinking and plan of attack on multiple fronts. Oh,
  that analogy is so militaristic, I'd revise more peacefully but ...
  time. :)
 
  1. We need better page-based design and navigation for many of our docs.
  I'm working with the Foundation on a redesign. This may include simpler
  source files.
  2. We still need book-like output. Examples of books include the
  Installation Guides, Operations Guide, the Security Guide, and probably
  the Architecture Design Guide. Every other bit of content can go into
  pages if we have decent design, information architecture, navigation,
  and versioning. Except maybe the API reference [0], that's a special beast.
  3. We need better maintenance and care of app developer docs like the
  API Reference. This also includes simpler source files.
 
 Just curious, has anyone considered rejigging things so that each
 component has a single definition of its API that could then be used to
 mechanically generate both the API validation code as well as the API
 reference documentation?

One idea related to the above, Nova will be able to provide API docs by
auto-generating the docs from JSON-Home and JSON-Schema(API validation
code). JSON-Home can provide API URLs, but it doesn't cover how to provide
JSON-Schema now. If we make a consistent way for doing that in OpenStack
components, we can get the docs on the same way/format. That was we told
on the other thread[1].

Thanks
Ken'ichi Ohmichi

---
[1]: http://lists.openstack.org/pipermail/openstack-dev/2014-October/047635.html


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Thierry Carrez
Jay Pipes wrote:
 On 10/03/2014 09:18 PM, Zane Bitter wrote:
 The prospect of a much larger tent with many more projects in
 OpenStack-proper shines a spotlight on the scalability of the Docs team,
 and in particular how they decide which projects are important to work
 on directly.
 
 I don't believe that a ticket to live under the OpenStack tent should
 come with the expectation that the Docs team is required to write
 documentation for the project.
 
 IMHO, it should be up to the project itself to provide the resources to
 work *under the guidance* of the Docs team to write developer, end user
 and operator documentation. The Docs team members should be able to play
 an advisory role for new projects, helping them understand the automated
 doc processes, the way that common doc infrastructure works, and
 techniques for writing useful documentation consistent with other projects.

I'd like to generalize that beyond Docs, because the same issue applies
to all other horizontal teams.

There are multiple ways an horizontal team can declare its commitment,
and I agree we should never assume that a TC decision (new integrated
project!) implies more work for the team (Docs now has to support this
as well). That's the way it currently works, and yes, it doesn't scale.
It didn't scale early with Docs, so they opted out of supporting all
integrated projects early on.

So in summary:
- ticket to live under the OpenStack big tent should never come with
expectation that any horizontal team will do the work for that project
directly
- horizontal teams may decide to directly do the work for any number of
projects
- corollary #1: horizontal teams may decide to commit to directly doing
the work for a mostly-static ring0 (or not)
- corollary #2: horizontal teams may decide to not directly do the work
for any project
- horizontal teams should build processes and tools to facilitate and
guide the work of projects in the big tent in their area of expertise

-- 
Thierry Carrez (ttx)

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Zane Bitter

On 06/10/14 06:07, Thierry Carrez wrote:

Jay Pipes wrote:

On 10/03/2014 09:18 PM, Zane Bitter wrote:

The prospect of a much larger tent with many more projects in
OpenStack-proper shines a spotlight on the scalability of the Docs team,
and in particular how they decide which projects are important to work
on directly.


I don't believe that a ticket to live under the OpenStack tent should
come with the expectation that the Docs team is required to write
documentation for the project.

IMHO, it should be up to the project itself to provide the resources to
work *under the guidance* of the Docs team to write developer, end user
and operator documentation. The Docs team members should be able to play
an advisory role for new projects, helping them understand the automated
doc processes, the way that common doc infrastructure works, and
techniques for writing useful documentation consistent with other projects.


I'd like to generalize that beyond Docs, because the same issue applies
to all other horizontal teams.

There are multiple ways an horizontal team can declare its commitment,
and I agree we should never assume that a TC decision (new integrated
project!) implies more work for the team (Docs now has to support this
as well). That's the way it currently works, and yes, it doesn't scale.
It didn't scale early with Docs, so they opted out of supporting all
integrated projects early on.

So in summary:
- ticket to live under the OpenStack big tent should never come with
expectation that any horizontal team will do the work for that project
directly
- horizontal teams may decide to directly do the work for any number of
projects
- corollary #1: horizontal teams may decide to commit to directly doing
the work for a mostly-static ring0 (or not)
- corollary #2: horizontal teams may decide to not directly do the work
for any project
- horizontal teams should build processes and tools to facilitate and
guide the work of projects in the big tent in their area of expertise


+1

So it seems like there is general agreement that we don't need/want the 
TC to tell horizontal teams what to work on, and that isn't one of the 
reasons for ring0/ring compute/Layer 1 to be a thing?


cheers,
Zane.

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Adam Lawson
I personally believe that delegating the task of documentation to
individual projects would be a huge mistake for one big reason:
documentation exists to understand how everything works within the context
of the solution as a whole. Very hard to do that consistently across all
projects with the docs team entrenched in developing individual products.

Plus, enterprise adoption of the open cloud *requires* documentation that
isn't an after thought. Writing code and trying to set aside some time to
document is the sheer definition of turning documentation an afterthought -
and no superior product has ever come from that sort of model.



*Adam Lawson*

AQORN, Inc.
427 North Tatnall Street
Ste. 58461
Wilmington, Delaware 19801-2230
Toll-free: (844) 4-AQORN-NOW ext. 101
International: +1 302-387-4660
Direct: +1 916-246-2072


On Mon, Oct 6, 2014 at 8:40 AM, Zane Bitter zbit...@redhat.com wrote:

 On 06/10/14 06:07, Thierry Carrez wrote:

 Jay Pipes wrote:

 On 10/03/2014 09:18 PM, Zane Bitter wrote:

 The prospect of a much larger tent with many more projects in
 OpenStack-proper shines a spotlight on the scalability of the Docs team,
 and in particular how they decide which projects are important to work
 on directly.


 I don't believe that a ticket to live under the OpenStack tent should
 come with the expectation that the Docs team is required to write
 documentation for the project.

 IMHO, it should be up to the project itself to provide the resources to
 work *under the guidance* of the Docs team to write developer, end user
 and operator documentation. The Docs team members should be able to play
 an advisory role for new projects, helping them understand the automated
 doc processes, the way that common doc infrastructure works, and
 techniques for writing useful documentation consistent with other
 projects.


 I'd like to generalize that beyond Docs, because the same issue applies
 to all other horizontal teams.

 There are multiple ways an horizontal team can declare its commitment,
 and I agree we should never assume that a TC decision (new integrated
 project!) implies more work for the team (Docs now has to support this
 as well). That's the way it currently works, and yes, it doesn't scale.
 It didn't scale early with Docs, so they opted out of supporting all
 integrated projects early on.

 So in summary:
 - ticket to live under the OpenStack big tent should never come with
 expectation that any horizontal team will do the work for that project
 directly
 - horizontal teams may decide to directly do the work for any number of
 projects
 - corollary #1: horizontal teams may decide to commit to directly doing
 the work for a mostly-static ring0 (or not)
 - corollary #2: horizontal teams may decide to not directly do the work
 for any project
 - horizontal teams should build processes and tools to facilitate and
 guide the work of projects in the big tent in their area of expertise


 +1

 So it seems like there is general agreement that we don't need/want the TC
 to tell horizontal teams what to work on, and that isn't one of the reasons
 for ring0/ring compute/Layer 1 to be a thing?

 cheers,
 Zane.


 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Jay Pipes

On 10/06/2014 12:44 PM, Adam Lawson wrote:

I personally believe that delegating the task of documentation to
individual projects would be a huge mistake for one big reason:
documentation exists to understand how everything works within the
context of the solution as a whole. Very hard to do that consistently
across all projects with the docs team entrenched in developing
individual products.

Plus, enterprise adoption of the open cloud /requires/ documentation
that isn't an after thought. Writing code and trying to set aside some
time to document is the sheer definition of turning documentation an
afterthought - and no superior product has ever come from that sort of
model.


I hear your concerns about the possibility of getting documentation that 
is either inconsistent (with respect to the other OpenStack projects) or 
not written for the right audience if we only have developer 
contributors writing documentation. You have an excellent and prescient 
point.


However, with my proposal, I was only saying that being under the 
OpenStack tent should not come with an automatic gift of resources from 
the excellent OpenStack Docs horizontal team. This process cannot scale. 
Instead, I believe it should be incumbent on the joining project to 
provide resources to work *with* the horizontal Docs team to provide 
foundational documentation for end users and operators. The Docs team 
can and should be advisors to the project contributors in how to write 
effective documentation targeted at non-developer contributors.


In addition, please see my proposal that projects applying to be in the 
OpenStack tent would have a requirement to name both a Docs liaison as 
well as a Release Management liaison. [1]


Best,
-jay

[1] 
http://www.joinfu.com/2014/09/answering-the-existential-question-in-openstack/


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Adam Lawson
I like your suggestion about the Docs team being advisors. I would submit
however (my opinion here) that whether or not there are enough resources on
the Doc'n team to handle Openstack's current list of integrated programs,
offloading the work to individual projects exchanges one challenge
(scalability) with another problem (quality). Using that approach, doc bugs
will get triaged with the other project bugs and potentially distracts
developers from doing what they do best - writing and fixing code. And what
happens when you only have time to fix a feature or work on documentation?
Focus on features and performance/stability are going to win. Every time.
And they should because that what the program teams should be focused on.
That means we start down the road heavy on code because developers can't do
everything, making them light on documentation forcing a catch-up process
to ensure which requires a special team to preserve momentum, bringing us
back to where we are now. I've been there before. And I'm sure others have
as well.

I've always been a big proponent of exploiting strengths vs building on
weaknesses and I'm going to step out on a limb here and speak to strengths
which may get me into hot water with some so I want to apologize in
advance. ; )

If a team of developers is tasked to produce all of the documentation for
enterprise consumers, I hate to say it like this but you'll end up with
highly-targeted documentation that makes sense to a developer and possibly
low-level engineers. That level of detail is probably best served in
README, wikis and mailing lists. It isn't effective as a user's manual.
Even with coaching, we'd be coaching folks to do things they aren't good
at. Same goes for a solution architect writing documentation the other way
around - you end up with documentation that speaks so broad, it fails to
make the impact that a targeted/focused approach is needed by the
engineering consumers.

While documentation produced by each individual project makes a special
kind of impact, it must be one spoke - not the entire wheel. I love the
idea of advisors and they should provide the first draft but I also believe
a dedicated team is needed to ensure quality doesn't suffer.


*Adam Lawson*

AQORN, Inc.
427 North Tatnall Street
Ste. 58461
Wilmington, Delaware 19801-2230
Toll-free: (844) 4-AQORN-NOW ext. 101
International: +1 302-387-4660
Direct: +1 916-246-2072


On Mon, Oct 6, 2014 at 9:59 AM, Jay Pipes jaypi...@gmail.com wrote:

 On 10/06/2014 12:44 PM, Adam Lawson wrote:

 I personally believe that delegating the task of documentation to
 individual projects would be a huge mistake for one big reason:
 documentation exists to understand how everything works within the
 context of the solution as a whole. Very hard to do that consistently
 across all projects with the docs team entrenched in developing
 individual products.

 Plus, enterprise adoption of the open cloud /requires/ documentation
 that isn't an after thought. Writing code and trying to set aside some
 time to document is the sheer definition of turning documentation an
 afterthought - and no superior product has ever come from that sort of
 model.


 I hear your concerns about the possibility of getting documentation that
 is either inconsistent (with respect to the other OpenStack projects) or
 not written for the right audience if we only have developer contributors
 writing documentation. You have an excellent and prescient point.

 However, with my proposal, I was only saying that being under the
 OpenStack tent should not come with an automatic gift of resources from the
 excellent OpenStack Docs horizontal team. This process cannot scale.
 Instead, I believe it should be incumbent on the joining project to provide
 resources to work *with* the horizontal Docs team to provide foundational
 documentation for end users and operators. The Docs team can and should be
 advisors to the project contributors in how to write effective
 documentation targeted at non-developer contributors.

 In addition, please see my proposal that projects applying to be in the
 OpenStack tent would have a requirement to name both a Docs liaison as well
 as a Release Management liaison. [1]

 Best,
 -jay

 [1] http://www.joinfu.com/2014/09/answering-the-existential-
 question-in-openstack/


 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Jay Pipes

On 10/06/2014 01:39 PM, Adam Lawson wrote:

I like your suggestion about the Docs team being advisors. I would
submit however (my opinion here) that whether or not there are enough
resources on the Doc'n team to handle Openstack's current list of
integrated programs, offloading the work to individual projects
exchanges one challenge (scalability) with another problem (quality).
Using that approach, doc bugs will get triaged with the other project
bugs and potentially distracts developers from doing what they do best -
writing and fixing code. And what happens when you only have time to fix
a feature or work on documentation? Focus on features and
performance/stability are going to win. Every time. And they should
because that what the program teams should be focused on. That means we
start down the road heavy on code because developers can't do
everything, making them light on documentation forcing a catch-up
process to ensure which requires a special team to preserve momentum,
bringing us back to where we are now. I've been there before. And I'm
sure others have as well.

I've always been a big proponent of exploiting strengths vs building on
weaknesses and I'm going to step out on a limb here and speak to
strengths which may get me into hot water with some so I want to
apologize in advance. ; )

If a team of developers is tasked to produce all of the documentation
for enterprise consumers, I hate to say it like this but you'll end up
with highly-targeted documentation that makes sense to a developer and
possibly low-level engineers. That level of detail is probably best
served in README, wikis and mailing lists. It isn't effective as a
user's manual. Even with coaching, we'd be coaching folks to do things
they aren't good at. Same goes for a solution architect writing
documentation the other way around - you end up with documentation that
speaks so broad, it fails to make the impact that a targeted/focused
approach is needed by the engineering consumers.

While documentation produced by each individual project makes a special
kind of impact, it must be one spoke - not the entire wheel. I love the
idea of advisors and they should provide the first draft but I also
believe a dedicated team is needed to ensure quality doesn't suffer.


I guess I wasn't clear in my suggestion. I am proposing that the joining 
project be responsible for bringing resources to the table -- and not 
developer resources, but tech writer resources. I think developers can 
and should work with the Docs team, but I also think that projects 
should hire or source tech writers themselves to handle the end user and 
operator documentation.


Best,
-jay

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Chris Friesen

On 10/06/2014 11:39 AM, Adam Lawson wrote:

I like your suggestion about the Docs team being advisors. I would
submit however (my opinion here) that whether or not there are enough
resources on the Doc'n team to handle Openstack's current list of
integrated programs, offloading the work to individual projects
exchanges one challenge (scalability) with another problem (quality).
Using that approach, doc bugs will get triaged with the other project
bugs and potentially distracts developers from doing what they do best -
writing and fixing code.


I think the point is that the individual projects can't have just 
developers...they also need to have people responsible for release 
management, integration testing, infrastructure, documentation, etc.


Chris


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-06 Thread Anne Gentle
On Mon, Oct 6, 2014 at 12:52 PM, Jay Pipes jaypi...@gmail.com wrote:

 On 10/06/2014 01:39 PM, Adam Lawson wrote:

 I like your suggestion about the Docs team being advisors. I would
 submit however (my opinion here) that whether or not there are enough
 resources on the Doc'n team to handle Openstack's current list of
 integrated programs, offloading the work to individual projects
 exchanges one challenge (scalability) with another problem (quality).
 Using that approach, doc bugs will get triaged with the other project
 bugs and potentially distracts developers from doing what they do best -
 writing and fixing code. And what happens when you only have time to fix
 a feature or work on documentation? Focus on features and
 performance/stability are going to win. Every time. And they should
 because that what the program teams should be focused on. That means we
 start down the road heavy on code because developers can't do
 everything, making them light on documentation forcing a catch-up
 process to ensure which requires a special team to preserve momentum,
 bringing us back to where we are now. I've been there before. And I'm
 sure others have as well.

 I've always been a big proponent of exploiting strengths vs building on
 weaknesses and I'm going to step out on a limb here and speak to
 strengths which may get me into hot water with some so I want to
 apologize in advance. ; )

 If a team of developers is tasked to produce all of the documentation
 for enterprise consumers, I hate to say it like this but you'll end up
 with highly-targeted documentation that makes sense to a developer and
 possibly low-level engineers. That level of detail is probably best
 served in README, wikis and mailing lists. It isn't effective as a
 user's manual. Even with coaching, we'd be coaching folks to do things
 they aren't good at. Same goes for a solution architect writing
 documentation the other way around - you end up with documentation that
 speaks so broad, it fails to make the impact that a targeted/focused
 approach is needed by the engineering consumers.

 While documentation produced by each individual project makes a special
 kind of impact, it must be one spoke - not the entire wheel. I love the
 idea of advisors and they should provide the first draft but I also
 believe a dedicated team is needed to ensure quality doesn't suffer.


 I guess I wasn't clear in my suggestion. I am proposing that the joining
 project be responsible for bringing resources to the table -- and not
 developer resources, but tech writer resources. I think developers can and
 should work with the Docs team, but I also think that projects should hire
 or source tech writers themselves to handle the end user and operator
 documentation.


This is happening with some projects and I always encourage companies
hiring for OpenStack devs should also hire writers to keep up with those
devs.

Sometimes the tech writer is assigned only to the API docs not the operator
docs. Or all sorts of other combinations. But yes, the idea is that the
enterprise doc teams should also dedicate some of their work to upstream
patching.

And yes, I agree with the sentiment that it's pretty useless to document
any project standalone for anyone except contributor devs. Users,
operators, should write for users and operators upstream. Contrib devs
write for devs in the commuity/upstream. Also hire tech writers who are
good at advocating for particular groups and have them write for upstream
as well. Lana Brindley and I are talking about that at the Summit Monday at
17:10 http://sched.co/1qeSZbp

Nick Chase and I are working on a report about the balance between meeting
the needs of community doc contributors and finding resources for
enterprise-level deliverables. It's complicated, isn't it? It's a balancing
act.

Great discussion.
Anne


 Best,
 -jay


 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-05 Thread Maish Saidel-Keesing

On 05/10/2014 06:00, Jay Pipes wrote:
 On 10/03/2014 09:18 PM, Zane Bitter wrote:
 The prospect of a much larger tent with many more projects in
 OpenStack-proper shines a spotlight on the scalability of the Docs team,
 and in particular how they decide which projects are important to work
 on directly.

 I don't believe that a ticket to live under the OpenStack tent should
 come with the expectation that the Docs team is required to write
 documentation for the project.

 IMHO, it should be up to the project itself to provide the resources
 to work *under the guidance* of the Docs team to write developer, end
 user and operator documentation. The Docs team members should be able
 to play an advisory role for new projects, helping them understand the
 automated doc processes, the way that common doc infrastructure works,
 and techniques for writing useful documentation consistent with other
 projects.

 Best,
 -jay

 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
A huge +1 on this!

You cannot expect the Docs team to understand and document a project -
on the project team knows the ins and outs of the code, what it can do,
and how to use it.

This does not mean it should be a free for all. Work *with* the the Docs
team to make the documentation standard and consistent across all of
OpenStack.

-- 
Maish Saidel-Keesing


___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-05 Thread Davanum Srinivas
One tool that ASF infra folks came up with was the Apache CMS, this
helps the individual projects contribute to maintaining their
documentation. They used Markdown format. Since we use DocBook, we
could use a converter like pandoc (http://johnmacfarlane.net/pandoc/)
later in the life cycle to use as input to our tools i guess.

http://www.apache.org/dev/cmsref.html
http://apache.org/dev/cms.html

A quick tutorial is at - https://www.youtube.com/watch?v=xcDZN3Lu6HA

thanks,
dims

On Sat, Oct 4, 2014 at 11:00 PM, Jay Pipes jaypi...@gmail.com wrote:
 On 10/03/2014 09:18 PM, Zane Bitter wrote:

 The prospect of a much larger tent with many more projects in
 OpenStack-proper shines a spotlight on the scalability of the Docs team,
 and in particular how they decide which projects are important to work
 on directly.


 I don't believe that a ticket to live under the OpenStack tent should come
 with the expectation that the Docs team is required to write documentation
 for the project.

 IMHO, it should be up to the project itself to provide the resources to work
 *under the guidance* of the Docs team to write developer, end user and
 operator documentation. The Docs team members should be able to play an
 advisory role for new projects, helping them understand the automated doc
 processes, the way that common doc infrastructure works, and techniques for
 writing useful documentation consistent with other projects.

 Best,
 -jay

 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



-- 
Davanum Srinivas :: https://twitter.com/dims

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Sean Dague
On 10/04/2014 12:26 AM, Chris Friesen wrote:
 On 10/03/2014 07:50 PM, Anne Gentle wrote:
 
 Here's my current thinking and plan of attack on multiple fronts. Oh,
 that analogy is so militaristic, I'd revise more peacefully but ...
 time. :)

 1. We need better page-based design and navigation for many of our docs.
 I'm working with the Foundation on a redesign. This may include simpler
 source files.
 2. We still need book-like output. Examples of books include the
 Installation Guides, Operations Guide, the Security Guide, and probably
 the Architecture Design Guide. Every other bit of content can go into
 pages if we have decent design, information architecture, navigation,
 and versioning. Except maybe the API reference [0], that's a special
 beast.
 3. We need better maintenance and care of app developer docs like the
 API Reference. This also includes simpler source files.
 
 Just curious, has anyone considered rejigging things so that each
 component has a single definition of its API that could then be used to
 mechanically generate both the API validation code as well as the API
 reference documentation?
 
 It seems silly to have to do the same work twice.  That's what computers
 are for. :)
 
 Or is the up-front effort too high to make it worthwhile?

This actually even came up on yesterday's bootstrapping hour. The point
I think that Anne made quite well is that audience matters if you want
to do it well (and not have it all come out like mud). It turns out what
you provide for machines, is different than what you provide for devs,
is different than what you provide for operators, is different than what
you provide for users.

It's a dev mindset trap that we can define it once in a language that
makes sense to us, and just build a bunch of generators to turn it into
understanding for everyone else. I know I fall victim to that a bunch.

-Sean

-- 
Sean Dague
http://dague.net

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Anne Gentle
On Fri, Oct 3, 2014 at 11:26 PM, Chris Friesen chris.frie...@windriver.com
wrote:

 On 10/03/2014 07:50 PM, Anne Gentle wrote:

  Here's my current thinking and plan of attack on multiple fronts. Oh,
 that analogy is so militaristic, I'd revise more peacefully but ...
 time. :)

 1. We need better page-based design and navigation for many of our docs.
 I'm working with the Foundation on a redesign. This may include simpler
 source files.
 2. We still need book-like output. Examples of books include the
 Installation Guides, Operations Guide, the Security Guide, and probably
 the Architecture Design Guide. Every other bit of content can go into
 pages if we have decent design, information architecture, navigation,
 and versioning. Except maybe the API reference [0], that's a special
 beast.
 3. We need better maintenance and care of app developer docs like the
 API Reference. This also includes simpler source files.


 Just curious, has anyone considered rejigging things so that each
 component has a single definition of its API that could then be used to
 mechanically generate both the API validation code as well as the API
 reference documentation?

 It seems silly to have to do the same work twice.  That's what computers
 are for. :)

 Or is the up-front effort too high to make it worthwhile?


To me, the upfront effort is better spent in better API docs. Starting with
generated is fine, but generated API reference documentation doesn't tell
users or quality engineers what's intended so that they can test APIs or
write apps that won't break. Some reviewers were going to allow 200-299
error codes to get into the docs as a valid response since that's what the
code does. [0] [1] That doesn't help users.

We do talk about generating API docs, and testing APIs, and testing SDKs,
quite a bit. Check out yesterday's Bootstrapping Hour [3] for more
discussion about the balancing act and tradeoffs in generated docs. I know
I toe the line a lot (not tow the line in this case, literally my toes are
on a fine line). :)

So great to know we're all thinking through this. It's a huge effort and we
should optimize within an inch of that line.
Thanks -
Anne

[0] https://review.openstack.org/#/c/120622/
[1] https://review.openstack.org/#/c/117193/
[2] https://www.youtube.com/watch?v=n2I3PFuoNj4



 Chris


 ___
 OpenStack-dev mailing list
 OpenStack-dev@lists.openstack.org
 http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Jay Pipes

On 10/03/2014 09:18 PM, Zane Bitter wrote:

The prospect of a much larger tent with many more projects in
OpenStack-proper shines a spotlight on the scalability of the Docs team,
and in particular how they decide which projects are important to work
on directly.


I don't believe that a ticket to live under the OpenStack tent should 
come with the expectation that the Docs team is required to write 
documentation for the project.


IMHO, it should be up to the project itself to provide the resources to 
work *under the guidance* of the Docs team to write developer, end user 
and operator documentation. The Docs team members should be able to play 
an advisory role for new projects, helping them understand the automated 
doc processes, the way that common doc infrastructure works, and 
techniques for writing useful documentation consistent with other projects.


Best,
-jay

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-04 Thread Joshua Harlow



On Sat, Oct 4, 2014 at 8:00 PM, Jay Pipes jaypi...@gmail.com wrote:

On 10/03/2014 09:18 PM, Zane Bitter wrote:

The prospect of a much larger tent with many more projects in
OpenStack-proper shines a spotlight on the scalability of the Docs 
team,
and in particular how they decide which projects are important to 
work

on directly.


I don't believe that a ticket to live under the OpenStack tent should 
come with the expectation that the Docs team is required to write 
documentation for the project.


IMHO, it should be up to the project itself to provide the resources 
to work *under the guidance* of the Docs team to write developer, end 
user and operator documentation. The Docs team members should be able 
to play an advisory role for new projects, helping them understand 
the automated doc processes, the way that common doc infrastructure 
works, and techniques for writing useful documentation consistent 
with other projects.


Best,
-jay


Amen to that, it is our responsibility as developers to do this, for 
the benefit of operators, developers, historians, ..., and users of 
openstack.


And really it isn't that hard, you just have to devote some time to do 
it (take 1/2 of a day a week to devote to doing docs for your project). 
Eventually all those 1/2 of days add up to a decent set of usable docs 
for people using your project/library/other... If we had more people 
spending 1/2 or 1/4 a day a week on improving docstrings, improving 
api/sphinx docs, improving diagrams we would IMHO be in a much better 
position with respect to on-boarding new developers and making it so 
that existing developers can understand prior architectural decisions 
(which is important for a variety of reasons, including but not limited 
to 'knowing what the reason for this code was' which can be useful 
when/if refactoring, knowing what the reason for this code was when 
adding new tests...).


IMHO we shouldn't be leaning on the docs team to do our docs, just like 
we shouldn't be leaning on the TC to say what is 'blessed' or what 
isn't; these roles should be advisory and I think they should be 
primarily spreading best practices, and leading by example (which I 
believe makes good leadership and a healthy community).


My 2 cents,

Josh




___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev



___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev


Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-03 Thread Anne Gentle
On Fri, Oct 3, 2014 at 8:18 PM, Zane Bitter zbit...@redhat.com wrote:

 Amidst all the discussion about layers and tents there has been this
 lurking issue about Docs and their need to prioritise work that we haven't
 really done a deep dive on yet. I'd like to start that discussion by
 summarising my understanding of the situation, and hopefully Anne and
 others can jump in and tell me what I've gotten horribly wrong.

 AIUI back in the day, all of the documentation for OpenStack was handled
 in a centralised way by the Docs team. We can all agree that doesn't scale,
 and that was recognised early on during the project's expansion.

 The current system is something of a hybrid model - for some subset of
 official projects considered important, the Docs team is directly
 responsible; for the others, the project team has to write the
 documentation. The docs team is available to provide support and tools for
 other official projects.


I think the Docs team isn't directly responsible for any project; we work
with all projects.


 It's not clear how important is currently defined... one suspects it's
 by date of accession ;)


There's more and more docs coverage in the common docs repos the longer a
project has been around, but that's not always due to doc team only work.

This wiki page attempts to describe current integrating/incubating
processing for docs.
https://wiki.openstack.org/wiki/Documentation/IncubateIntegrate

Thing is, it's tough to say that any given project has completed docs. Nova
still probably has the lead with the most doc bugs since Xen is barely
documented and there are a lot of doc bugs for the Compute API versions. So
it's possible to measure with our crude instruments and even with those
measurements, inner chewy center projects could be called under-documented.


 The prospect of a much larger tent with many more projects in
 OpenStack-proper shines a spotlight on the scalability of the Docs team,
 and in particular how they decide which projects are important to work on
 directly.

 There seems to be an implicit argument floating around that there are a
 bunch of projects that depend on each other and we need to create a
 governance structure around blessing this, rather than merely observing it
 as an emergent property of the gate, at least in part because that's the
 only way to tell the Docs team what is important.

 There are two problems with this line of thought IMHO. The obvious one is
 of course that the number of bi-directional dependencies of a project is
 not *in any way* related to how important it is to have documentation for
 it. It makes about as much sense as saying that we're only going to
 document projects whose names contain the letter 't'.

 The second is that it implies that the Docs team are the only people in
 OpenStack who need the TC to tell them what to work on. Developers
 generally work on what they or their employer feels is important. If you
 see something being neglected you either try to help out or pass the word
 up that more resources are needed in a particular area. Is there any reason
 to think it wouldn't work the same with technical writers? Is anyone
 seriously worried that Nova will go undocumented unless the TC creates a
 project structure that specifically calls it out as important?

 What I'm envisioning is that we would move to a completely distributed
 model, where the documentation for each project is owned by that project.
 People who care about the project being documented would either work on it
 themselves and/or recruit developers and/or technical writers to do so. The
 Docs program itself would concentrate on very high-level
 non-project-specific documentation and on standards and tools to help
 deliver a consistent presentation across projects. Of course we would
 expect there to be considerable overlap between the people contributing to
 the Docs program itself and those contributing to documentation of the
 various projects. Docs would also have a formal liaison program to ensure
 that information is disseminated rapidly and evenly.


I still maintain the thinking that common OpenStack docs are very valuable
and the information architecture across projects could only go so far to
truly serve users.

Here's my current thinking and plan of attack on multiple fronts. Oh, that
analogy is so militaristic, I'd revise more peacefully but ... time. :)

1. We need better page-based design and navigation for many of our docs.
I'm working with the Foundation on a redesign. This may include simpler
source files.
2. We still need book-like output. Examples of books include the
Installation Guides, Operations Guide, the Security Guide, and probably the
Architecture Design Guide. Every other bit of content can go into pages if
we have decent design, information architecture, navigation, and
versioning. Except maybe the API reference [0], that's a special beast.
3. We need better maintenance and care of app developer docs like the API

Re: [openstack-dev] [all][docs][tc] How to scale Documentation

2014-10-03 Thread Chris Friesen

On 10/03/2014 07:50 PM, Anne Gentle wrote:


Here's my current thinking and plan of attack on multiple fronts. Oh,
that analogy is so militaristic, I'd revise more peacefully but ...
time. :)

1. We need better page-based design and navigation for many of our docs.
I'm working with the Foundation on a redesign. This may include simpler
source files.
2. We still need book-like output. Examples of books include the
Installation Guides, Operations Guide, the Security Guide, and probably
the Architecture Design Guide. Every other bit of content can go into
pages if we have decent design, information architecture, navigation,
and versioning. Except maybe the API reference [0], that's a special beast.
3. We need better maintenance and care of app developer docs like the
API Reference. This also includes simpler source files.


Just curious, has anyone considered rejigging things so that each 
component has a single definition of its API that could then be used to 
mechanically generate both the API validation code as well as the API 
reference documentation?


It seems silly to have to do the same work twice.  That's what computers 
are for. :)


Or is the up-front effort too high to make it worthwhile?

Chris

___
OpenStack-dev mailing list
OpenStack-dev@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev