[openstack-dev] [Ceilometer] Documentation and patches

Anne Gentle annegentle at justwriteclick.com
Fri Aug 30 13:33:40 UTC 2013


I applaud Julien's note and we're happy to work with the teams on finding
where docs should go. Julien's feeling very behind, and I'm sure other
projects are feeling the same.

We all have to set priorities. Here's where I'd start.

Log doc bugs in openstack-manuals for:
installation
configuration
day-to-day running
end-user tasks
admin tasks
troubleshooting

Log doc bugs in openstack-api-site for:
API reference docs

Ensure your configuration information is updated as it is now being scraped
with a script to go into the Config Ref.

Assign knowledgeable team members to the doc bugs. Come to #openstack-doc
on IRC to ask which files to update. Recruit writers and reviewers.

Go go go!

Thanks,
Anne



On Fri, Aug 30, 2013 at 8:22 AM, Davanum Srinivas <davanum at gmail.com> wrote:

> How about mandating that when one adds a DocImpact in a review it should
> have a url to an etherpad/wiki with sufficient information for the doc
> team? yes, +1 to let docs team figure out where to fit it into existing
> guides.
>
> -- dims
>
>
> On Fri, Aug 30, 2013 at 9:01 AM, Russell Bryant <rbryant at redhat.com>wrote:
>
>> -----BEGIN PGP SIGNED MESSAGE-----
>> Hash: SHA1
>>
>> On 08/30/2013 08:39 AM, Julien Danjou wrote:
>> > Hi team,
>> >
>> > We need to get better at documentation. We are terrible at it. We
>> > let code go through the gates knowing that our documentation isn't
>> > up to date. We have features implemented 6 months ago still not
>> > documented. Nobody's going to do it for us.
>> >
>> > Therefore I strongly suggest that as soon as you spot that the
>> > documentation must be updated to reflect any change, you score -1
>> > the patchset to oblige the submitting developer to write some
>> > prose.
>>
>> This is something we could get better at across all of OpenStack.
>>
>> I've been thinking about proposing requiring docs *somewhere* for
>> everything that affects docs.  For small stuff, it could be explaining
>> it especially well in the commit message.  For larger stuff, it could
>> be covered on the blueprint or wiki page.
>>
>> I think at the least, we could provide some of the core information so
>> that the docs team is left with figuring out where best to fit it into
>> the existing guides, as opposed to generating the content from scratch.
>>
>> - --
>> Russell Bryant
>> -----BEGIN PGP SIGNATURE-----
>> Version: GnuPG v1.4.14 (GNU/Linux)
>> Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/
>>
>> iEYEARECAAYFAlIgl4wACgkQFg9ft4s9SAZxlACgq6BZVx8zW7XLxjis4FootwOD
>> qCMAoI3ztfBMetE13TJ3ZjZ+sLaQVPrx
>> =W0H0
>> -----END PGP SIGNATURE-----
>>
>> _______________________________________________
>> OpenStack-dev mailing list
>> OpenStack-dev at lists.openstack.org
>> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>>
>
>
>
> --
> Davanum Srinivas :: http://davanum.wordpress.com
>
> _______________________________________________
> OpenStack-dev mailing list
> OpenStack-dev at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
>
>


-- 
Anne Gentle
annegentle at justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20130830/722b7e3c/attachment.html>


More information about the OpenStack-dev mailing list