settingsLogin | Registersettings

[openstack-dev] [all][docs] recruiting for help with documentation tools

0 votes

With the changes we've made to docs processes upstream, every team
is going to need to build up their knowledge of how the new
documentation tools and jobs work. The docs team will still help,
but things will obviously go more smoothly if folks know how the
tools work, now that the bulk of the content is in-tree with the
code.

At the same time, the docs team could use help with developing and
maintaining those tools. We have a couple people working on them
now (me, Andreas, and Anne), but none of us is doing it full time.
I need to transition off of this work, so over the course of Queens
I will be trying to build up the skills of the existing team so
they do not need to rely on me so much. Also, Andreas and Anne have
said that they cannot commit to driving any work.

Although the documentation team has some skills in this area, they
could use help, so I would like to find a few people to join the
team specifically to work on the tooling (although if you wanted
to write documentation, too, no one will object).

Some of you have been helping informally (thank you!), but the
community shift is big enough that we need to account for the new
need a bit more formally. I think if we could find several people
who could give a small percentage of their time (10%?), we would
be well covered. There will not be work every week, but when there
is something to do it's likely to take a small extended period (1-2
days) to add a feature or resolve an issue. If we found 4-6 people,
I think we would be covered and have a sustainable group.

The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.

If you are interested in helping, please let me know by following
up to this thread, and then join #openstack-docs on IRC.

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
asked Aug 2, 2017 in openstack-dev by Doug_Hellmann (87,520 points)   4 5 13

6 Responses

0 votes

On 01.08.2017 21:35, Doug Hellmann wrote:
With the changes we've made to docs processes upstream, every team
is going to need to build up their knowledge of how the new
documentation tools and jobs work. The docs team will still help,
but things will obviously go more smoothly if folks know how the
tools work, now that the bulk of the content is in-tree with the
code.

At the same time, the docs team could use help with developing and
maintaining those tools. We have a couple people working on them
now (me, Andreas, and Anne), but none of us is doing it full time.
I need to transition off of this work, so over the course of Queens
I will be trying to build up the skills of the existing team so
they do not need to rely on me so much. Also, Andreas and Anne have
said that they cannot commit to driving any work.

Although the documentation team has some skills in this area, they
could use help, so I would like to find a few people to join the
team specifically to work on the tooling (although if you wanted
to write documentation, too, no one will object).

Some of you have been helping informally (thank you!), but the
community shift is big enough that we need to account for the new
need a bit more formally. I think if we could find several people
who could give a small percentage of their time (10%?), we would
be well covered. There will not be work every week, but when there
is something to do it's likely to take a small extended period (1-2
days) to add a feature or resolve an issue. If we found 4-6 people,
I think we would be covered and have a sustainable group.

The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.

If you are interested in helping, please let me know by following
up to this thread, and then join #openstack-docs on IRC.

+1

Doug


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

--
Best regards,
Bogdan Dobrelya,
Irc #bogdando


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by bdobreli_at_redhat.c (2,260 points)   2 3
0 votes

On Wed, Aug 2, 2017 at 2:25 PM, Bogdan Dobrelya bdobreli@redhat.com wrote:
On 01.08.2017 21:35, Doug Hellmann wrote:

With the changes we've made to docs processes upstream, every team
is going to need to build up their knowledge of how the new
documentation tools and jobs work. The docs team will still help,
but things will obviously go more smoothly if folks know how the
tools work, now that the bulk of the content is in-tree with the
code.

At the same time, the docs team could use help with developing and
maintaining those tools. We have a couple people working on them
now (me, Andreas, and Anne), but none of us is doing it full time.
I need to transition off of this work, so over the course of Queens
I will be trying to build up the skills of the existing team so
they do not need to rely on me so much. Also, Andreas and Anne have
said that they cannot commit to driving any work.

Although the documentation team has some skills in this area, they
could use help, so I would like to find a few people to join the
team specifically to work on the tooling (although if you wanted
to write documentation, too, no one will object).

Some of you have been helping informally (thank you!), but the
community shift is big enough that we need to account for the new
need a bit more formally. I think if we could find several people
who could give a small percentage of their time (10%?), we would
be well covered. There will not be work every week, but when there
is something to do it's likely to take a small extended period (1-2
days) to add a feature or resolve an issue. If we found 4-6 people,
I think we would be covered and have a sustainable group.

The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.

If you are interested in helping, please let me know by following
up to this thread, and then join #openstack-docs on IRC.

+1

Doug


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

--
Best regards,
Bogdan Dobrelya,
Irc #bogdando


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

+1


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Swapnil_Kulkarni (2,500 points)   2 3
0 votes

Doug Hellmann wrote:
[...]
The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.
[...]
Feels like the doc owners/liaisons that we are looking for in the Top 5
help wanted list[1] would be in a good position to help with that.
Should we extend the description of the need so that it's clearer that
help with maintaining the doc toolchain is also a top wanted thing ?

[1]
https://governance.openstack.org/tc/reference/top-5-help-wanted.html#documentation-owners

--
Thierry Carrez (ttx)


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Thierry_Carrez (57,480 points)   3 9 16
0 votes

Excerpts from Thierry Carrez's message of 2017-08-02 14:01:47 +0200:

Doug Hellmann wrote:

[...]
The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.
[...]
Feels like the doc owners/liaisons that we are looking for in the Top 5
help wanted list[1] would be in a good position to help with that.
Should we extend the description of the need so that it's clearer that
help with maintaining the doc toolchain is also a top wanted thing ?

[1]
https://governance.openstack.org/tc/reference/top-5-help-wanted.html#documentation-owners

I'm torn on that. On the one hand, I would like to recruit. On the
other, we do need far more content contributors than tool maintainers.
Let's wait and see. There were 2 responses to this thread already, so
maybe we won't need to go that far.

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Doug_Hellmann (87,520 points)   4 5 13
0 votes

Excerpts from Swapnil Kulkarni's message of 2017-08-02 14:35:49 +0530:

On Wed, Aug 2, 2017 at 2:25 PM, Bogdan Dobrelya bdobreli@redhat.com wrote:

On 01.08.2017 21:35, Doug Hellmann wrote:

With the changes we've made to docs processes upstream, every team
is going to need to build up their knowledge of how the new
documentation tools and jobs work. The docs team will still help,
but things will obviously go more smoothly if folks know how the
tools work, now that the bulk of the content is in-tree with the
code.

At the same time, the docs team could use help with developing and
maintaining those tools. We have a couple people working on them
now (me, Andreas, and Anne), but none of us is doing it full time.
I need to transition off of this work, so over the course of Queens
I will be trying to build up the skills of the existing team so
they do not need to rely on me so much. Also, Andreas and Anne have
said that they cannot commit to driving any work.

Although the documentation team has some skills in this area, they
could use help, so I would like to find a few people to join the
team specifically to work on the tooling (although if you wanted
to write documentation, too, no one will object).

Some of you have been helping informally (thank you!), but the
community shift is big enough that we need to account for the new
need a bit more formally. I think if we could find several people
who could give a small percentage of their time (10%?), we would
be well covered. There will not be work every week, but when there
is something to do it's likely to take a small extended period (1-2
days) to add a feature or resolve an issue. If we found 4-6 people,
I think we would be covered and have a sustainable group.

The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.

If you are interested in helping, please let me know by following
up to this thread, and then join #openstack-docs on IRC.

+1

Doug


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

--
Best regards,
Bogdan Dobrelya,
Irc #bogdando


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

+1

Thanks, Bogdan and Swapnil, I'm happy to have you on board!

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Doug_Hellmann (87,520 points)   4 5 13
0 votes

Excerpts from Doug Hellmann's message of 2017-08-01 15:35:35 -0400:

With the changes we've made to docs processes upstream, every team
is going to need to build up their knowledge of how the new
documentation tools and jobs work. The docs team will still help,
but things will obviously go more smoothly if folks know how the
tools work, now that the bulk of the content is in-tree with the
code.

At the same time, the docs team could use help with developing and
maintaining those tools. We have a couple people working on them
now (me, Andreas, and Anne), but none of us is doing it full time.
I need to transition off of this work, so over the course of Queens
I will be trying to build up the skills of the existing team so
they do not need to rely on me so much. Also, Andreas and Anne have
said that they cannot commit to driving any work.

Although the documentation team has some skills in this area, they
could use help, so I would like to find a few people to join the
team specifically to work on the tooling (although if you wanted
to write documentation, too, no one will object).

Some of you have been helping informally (thank you!), but the
community shift is big enough that we need to account for the new
need a bit more formally. I think if we could find several people
who could give a small percentage of their time (10%?), we would
be well covered. There will not be work every week, but when there
is something to do it's likely to take a small extended period (1-2
days) to add a feature or resolve an issue. If we found 4-6 people,
I think we would be covered and have a sustainable group.

The areas we need help are maintaining the doc build jobs, the
sphinx extensions in oslo.config and oslo.policy, the Sphinx theme,
and the template build tool in the openstack-manuals git repo. These
are all minimally complete, but there is definitely feature work
and bug fixing to do. I can guarantee that, if you sign up to help,
you will have a chance to land changes that will be visible for all
OpenStack users. At the start of Queens, I will be doing some
one-on-one training with volunteers to ensure they understand the
system we have in place now and help them start on some of the
remaining feature work.

If you are interested in helping, please let me know by following
up to this thread, and then join #openstack-docs on IRC.

Doug

If you want an idea of the sorts of work ahead, check out the tracking
pad: https://etherpad.openstack.org/p/doc-future-problems

Not everything on that list is related to the tools, but quite a lot is.

Doug


OpenStack Development Mailing List (not for usage questions)
Unsubscribe: OpenStack-dev-request@lists.openstack.org?subject:unsubscribe
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
responded Aug 2, 2017 by Doug_Hellmann (87,520 points)   4 5 13
...