1. Messages
  2. [release] idea for documentation reviewing in Boron

Re: [release] idea for documentation reviewing in Boron

Gao Kai
 

For the record.


-------- Forwarded Message --------
Subject: Re: [release] idea for documentation reviewing in Boron
Date: Wed, 24 Feb 2016 06:43:17 -0500
From: Colin Dixon <colin@...>
To: George Zhao <George.Y.Zhao@...>
CC: release@... <release@...>, documentation@... <documentation@...>


Wikis (or at least the ones I know of) are poorly suited to keeping multiple different versions of the same content (for different releases) up-to-date, so most pages are just for whatever release was current when they were written. To help with that, I created templates for each release here:
https://wiki.opendaylight.org/view/Wiki_gardening#Gardening_Templates

You can use them by doing {{Helium Release}} at the top of a page where you can replace Helium with whatever release you'd like. An example is this page:
https://wiki.opendaylight.org/view/OpenDaylight_Controller:MD-SAL:Toaster_Tutorial

Pretty much nobody uses those templates. They are nice though because they can be used to dynamically insert warnings about content when it gets out of date and also add pages to the relevant category for the release.

--Colin


On Tue, Feb 23, 2016 at 1:53 PM, George Zhao <George.Y.Zhao@...> wrote:

Pair up is a great idea.

 

One feedback I had is that in our document as well as wiki, it doesn’t mention the instructions are for which release version.

 

I think this is because when we write those instructions, we always assume it is for current version, and when we have a new current, we don’t go back to update old docs.

 

From: release-bounces@... [mailto:release-bounces@...] On Behalf Of Colin Dixon
Sent: Sunday, February 21, 2016 7:54 AM
To: documentation@...; release@...
Subject: [release] idea for documentation reviewing in Boron

 

In Boron, one idea I have to better distribute the burden of reviewing documentation is to have projects to documentation peer-review. I'm not 100% sure how to do it, but my first intuition is to pair projects up and require that they review each others documentation for clarity, grammar, spelling, formatting, etc. before the Documentation team reviews and merges it.

Thoughts?

--Colin




?
Attached Message Part

Join {z.archive.alto-dev@lists.opendaylight.org to automatically receive all group messages.