settingsLogin | Registersettings

[OpenStack-docs] Wrapup - Liberty Design Summit

0 votes

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi everyone,

I've (finally!) finished going through all the etherpads and summarising
them. You can read the full thing here:
https://wiki.openstack.org/wiki/Documentation/Liberty and the original
etherpads are still alive, linked from here:
https://wiki.openstack.org/wiki/Design_Summit/Liberty/Etherpads#Documentation

For the TL;DR version, I've summarised everything into a few key goals
for Liberty:

  • RST Conversion:

    • Install Guide
    • Cloud Admin Guide
    • HA Guide
    • CLI reference
  • Restructure user guides
  • Increased communication with documentation liaisons, other PTLs, and i18n
  • Update the way we select core team
  • Update contributor guides
  • Clean up the DocImpact bug workflow, and clean out old bugs
  • Find a way to get docs people more involved with dev groups (midcycles)
  • Increase collaboration with corporate contributors

If you think I've missed something, or you want to add commentary to any
of these goals, please feel free to contact me. I am, as always, happy
to go through things in more depth

Lana


Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJVZlTdAAoJELppzVb4+KUyM+sH+wb/vqLVPIQi/2AZleEBkXC5
cBwoiAriPYFj6poc69Qz6x8/IaLi5vekSkBsNeniWImnzJjMiawkg/yyFTT7pZ3f
sH0QjyZbjiJeyuy3voUs9lznn27Ho0Hlnc4JrD+6z9Gdsm20ZoVz4ISlfWrLRTa+
o4gxYQOm9j3Lq+2ZrJrBJ5FsuCHOSpqVpTYzMQGLYkJKYl/MELNxr1OhbFcd1tFs
r5VNanUVBl3F7Z60KdJe/ZWOmOLaz6mSI9tGprlitg/7LNckPYVoA1map20pdoA2
qZuBBJIv6iDCNmBZUzhatAMHN920m+fo04Bpf8kO+pciC9X1Roy/GVMVyyARCIw=
=uoHD
-----END PGP SIGNATURE-----


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
asked May 27, 2015 in openstack-docs by Lana_Brindley (6,210 points)   2 3 3

13 Responses

0 votes

On 05/28/2015 01:35 AM, Lana Brindley wrote:
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi everyone,

Thanks Lana for the writeup! I'll read later through all of it, having
this is great for me as I couldn't make it to Vancouver.

I've (finally!) finished going through all the etherpads and summarising
them. You can read the full thing here:
https://wiki.openstack.org/wiki/Documentation/Liberty and the original
etherpads are still alive, linked from here:
https://wiki.openstack.org/wiki/Design_Summit/Liberty/Etherpads#Documentation

For the TL;DR version, I've summarised everything into a few key goals
for Liberty:

  • RST Conversion:

    • Install Guide
    • Cloud Admin Guide
    • HA Guide
    • CLI reference
  • Restructure user guides
  • Increased communication with documentation liaisons, other PTLs, and i18n
  • Update the way we select core team
  • Update contributor guides

Whoever updates them, please avoid any duplication with
http://docs.openstack.org/infra/manual/developers.html and if there's
content missing, improve that one,

Andreas

  • Clean up the DocImpact bug workflow, and clean out old bugs
  • Find a way to get docs people more involved with dev groups (midcycles)
  • Increase collaboration with corporate contributors

If you think I've missed something, or you want to add commentary to any
of these goals, please feel free to contact me. I am, as always, happy
to go through things in more depth

Lana


Lana Brindley
Technical Writer
Rackspace Cloud Builders Australia
http://lanabrindley.com
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1

iQEcBAEBAgAGBQJVZlTdAAoJELppzVb4+KUyM+sH+wb/vqLVPIQi/2AZleEBkXC5
cBwoiAriPYFj6poc69Qz6x8/IaLi5vekSkBsNeniWImnzJjMiawkg/yyFTT7pZ3f
sH0QjyZbjiJeyuy3voUs9lznn27Ho0Hlnc4JrD+6z9Gdsm20ZoVz4ISlfWrLRTa+
o4gxYQOm9j3Lq+2ZrJrBJ5FsuCHOSpqVpTYzMQGLYkJKYl/MELNxr1OhbFcd1tFs
r5VNanUVBl3F7Z60KdJe/ZWOmOLaz6mSI9tGprlitg/7LNckPYVoA1map20pdoA2
qZuBBJIv6iDCNmBZUzhatAMHN920m+fo04Bpf8kO+pciC9X1Roy/GVMVyyARCIw=
=uoHD
-----END PGP SIGNATURE-----


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

--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

On 05/28/2015 10:41 AM, Andreas Jaeger wrote:

What about converting
https://wiki.openstack.org/wiki/Documentation/HowTo into a "OpenStack
Documentation Guide" as a first step. Followed by including
https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers into
this new guide (I think this is the contributor guide?). Followed by
including all of the rest flying around in the wiki.

At the moment the content provided in the wiki is not accurate and I do
not like that we do not fulfil ower own slogan "Documentation treated
like code" for our own documentation.

An initial migration of the content provided in the wiki to a RST guide
is straightforward and I could take care of it if we want to have such a
guide for us.

Christian.

--
Christian Berendt
Cloud Computing Solution Architect
Mail: berendt@b1-systems.de

B1 Systems GmbH
Osterfeldstraße 7 / 85088 Vohburg / http://www.b1-systems.de
GF: Ralph Dehner / Unternehmenssitz: Vohburg / AG: Ingolstadt,HRB 3537


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by christian_at_berendt (3,780 points)   3 8
0 votes

+1 and willing to help with this.

/Harry

On 05/28/2015 05:01 AM, Christian Berendt wrote:
On 05/28/2015 10:41 AM, Andreas Jaeger wrote:

At the moment the content provided in the wiki is not accurate and I do
not like that we do not fulfil ower own slogan "Documentation treated
like code" for our own documentation.

An initial migration of the content provided in the wiki to a RST guide
is straightforward and I could take care of it if we want to have such a
guide for us.

Christian.


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Sutton,_Harry_(HP_Co (180 points)  
0 votes

Hello!

The idea of a separate contributor guide is great, and I am willing to take
part in its creation/migration too.
Is there any plan or even spec for it?

Regards,
Olga

On Thu, May 28, 2015 at 2:55 PM, Sutton, Harry (HP Converged Systems &
Solutions ERT) harry.sutton@hp.com wrote:

+1 and willing to help with this.

/Harry

On 05/28/2015 05:01 AM, Christian Berendt wrote:

On 05/28/2015 10:41 AM, Andreas Jaeger wrote:

At the moment the content provided in the wiki is not accurate and I do
not like that we do not fulfil ower own slogan "Documentation treated
like code" for our own documentation.

An initial migration of the content provided in the wiki to a RST guide
is straightforward and I could take care of it if we want to have such a
guide for us.

Christian.


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


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Olga_Gusarenko (340 points)  
0 votes

On 05/28/2015 02:52 PM, Olga Gusarenko wrote:
Hello!

The idea of a separate contributor guide is great, and I am willing to
take part in its creation/migration too.
Is there any plan or even spec for it?

There is a contributor guide already:

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

Thanks, Andreas! I meant the contributor guide for the writers =), some
kind of a style guide, I suppose.

What about converting
https://wiki.openstack.org/wiki/Documentation/HowTo into a "OpenStack
Documentation Guide" as a first step.

Or have I misunderstood Christian's words?

Olga

On Thu, May 28, 2015 at 3:59 PM, Andreas Jaeger aj@suse.com wrote:

On 05/28/2015 02:52 PM, Olga Gusarenko wrote:

Hello!

The idea of a separate contributor guide is great, and I am willing to
take part in its creation/migration too.
Is there any plan or even spec for it?

There is a contributor guide already:

http://docs.openstack.org/infra/manual/developers.html

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

Andreas

-- Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Olga_Gusarenko (340 points)  
0 votes

On 05/28/2015 02:59 PM, Andreas Jaeger wrote:
There is a contributor guide already:

http://docs.openstack.org/infra/manual/developers.html

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

I think we are talking about different documents at the moment.

I am talking about converting the following wiki pages into an OpenStack
Documentation Guide:

https://wiki.openstack.org/wiki/Documentation/HowTo
https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers

Followed by everything inside the
https://wiki.openstack.org/wiki/Documentation namespace.

I think this content is not related to the developers guide, is it?

Christian.


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by christian_at_berendt (3,780 points)   3 8
0 votes

I thought we went down this road a release or two ago and decided against
using Gerrit for this content. If we want to try using Gerrit again, I
suggest we look at adding our content to the existing developer manual
rather than creating another guide. I'd rather point people to one place
rather than "look at X for general contribution instructions", "look at Y
for documentation conventions", etc.

On Thu, May 28, 2015 at 8:29 AM, Christian Berendt christian@berendt.io
wrote:

On 05/28/2015 02:59 PM, Andreas Jaeger wrote:

There is a contributor guide already:

http://docs.openstack.org/infra/manual/developers.html

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

I think we are talking about different documents at the moment.

I am talking about converting the following wiki pages into an OpenStack
Documentation Guide:

https://wiki.openstack.org/wiki/Documentation/HowTo
https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers

Followed by everything inside the
https://wiki.openstack.org/wiki/Documentation namespace.

I think this content is not related to the developers guide, is it?

Christian.


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


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Matt_Kassawara (5,380 points)   1 3 3
0 votes

On 05/28/2015 03:29 PM, Christian Berendt wrote:
On 05/28/2015 02:59 PM, Andreas Jaeger wrote:

There is a contributor guide already:

http://docs.openstack.org/infra/manual/developers.html

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

I think we are talking about different documents at the moment.

I am talking about converting the following wiki pages into an OpenStack
Documentation Guide:

https://wiki.openstack.org/wiki/Documentation/HowTo
https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers

Followed by everything inside the
https://wiki.openstack.org/wiki/Documentation namespace.

I think this content is not related to the developers guide, is it?

I think the following are duplicates - and if there's generic content in
it that's needed, move it to the Developer's guide:

https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Set_up_for_contribution

https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Set_up_git_and_git_review

https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Set_up_ssh

https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Set_up_repositories_and_work_locally

https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers#Accessing_Gerrit_over_HTTP.2FHTTPS

The HowTo page also contains duplicates.

But I'm fine with moving content from the wiki elsewhere as long as we
have no duplication,

Andreas
--
Andreas Jaeger aj@{suse.com,opensuse.org} Twitter/Identica: jaegerandi
SUSE LINUX GmbH, Maxfeldstr. 5, 90409 Nürnberg, Germany
GF: Felix Imendörffer, Jane Smithard, Dilip Upmanyu, Graham Norton,
HRB 21284 (AG Nürnberg)
GPG fingerprint = 93A3 365E CE47 B889 DF7F FED1 389A 563C C272 A126


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by Andreas_Jaeger (17,140 points)   2 3 4
0 votes

On Thu, May 28, 2015 at 8:56 AM, Matt Kassawara mkassawara@gmail.com
wrote:

I thought we went down this road a release or two ago and decided against
using Gerrit for this content. If we want to try using Gerrit again, I
suggest we look at adding our content to the existing developer manual
rather than creating another guide. I'd rather point people to one place
rather than "look at X for general contribution instructions", "look at Y
for documentation conventions", etc.

I think we had a Rackspace DocBook one at the time that was a behemoth that
we looked at. It might be nice to get a lighter-weight RST one integrated
with the Infra manual since all the teams need to know the doc contribution
mechanisms.

Anne

On Thu, May 28, 2015 at 8:29 AM, Christian Berendt christian@berendt.io
wrote:

On 05/28/2015 02:59 PM, Andreas Jaeger wrote:

There is a contributor guide already:

http://docs.openstack.org/infra/manual/developers.html

A documentation specific addentum to it or an extension to it would be
nice indeed - and a spec should indeed be written,

I think we are talking about different documents at the moment.

I am talking about converting the following wiki pages into an OpenStack
Documentation Guide:

https://wiki.openstack.org/wiki/Documentation/HowTo
https://wiki.openstack.org/wiki/Documentation/HowTo/FirstTimers

Followed by everything inside the
https://wiki.openstack.org/wiki/Documentation namespace.

I think this content is not related to the developers guide, is it?

Christian.


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


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

--
Anne Gentle
annegentle@justwriteclick.com


OpenStack-docs mailing list
OpenStack-docs@lists.openstack.org
http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
responded May 28, 2015 by annegentle_at_justwr (9,780 points)   2 5 6
...