Documentation Acceptance Process Proposal

[George Deka]

On Tue, 16 Nov 2004 08:06:41 -0600, John Hornbeck
<hornbeck at freeshell.org> wrote:
> On Tue, 2004-11-16 at 16:00 +0200, Alexander Poslavsky wrote:
> 
> 
> > On Tue, 16 Nov 2004 15:24:15 +0200, Sivan Green <sivan at piware.de> wrote:
> > >
> > >   The need for setting up some sort of doc team work scheme for
> > > accepting new wiki / offline docs has been felt for ages, so now let us
> >
> > agreed
> >
> > > Preliminaries for establishing a work accaptance process:
> > >
> > >      *  Setting up a wiki page  for people to link to their newly
> > > submitted WikiPage / Document. We should device a format for submission
> > > which would allow          us to contact the person who contributed, the
> >
> > Contacting people who write docs would be nice, is it possible in
> > zwiki to see who made a page?
You can go to the history and i think it tells you in there
> >
> > >          Tis can be  devided to :
> > >                        + FAQs
> > >                        + Howtos
> > >                        + Medium size pages / docs (tutorials)
> > >                        + Large documents (guides)
> > >
> > >     * Establish the documentation testing team:
> > >           * Have a list of people who would be willing to test drive new
> > > docs , comment and be commited to do it :)
> > >           * Have a list of people from core team who would be willing to
> > > also review, fix and test. (one or two).
> >
> > This we really need, how could we get a group of good people and who
> > would take care of the documentation-flow?
to take care of doc-flow we need to appoint people in certain position
such as 2-4? reviewers and 1 super-reviewer? -- see how it works quite
efficently for mozilla
> >
> > >
> > >     * Make sure our svn server is on and capable, to allow for
> > > submission of offline oriented or non wiki material for review and work.
> >
> > This seems to be getting better. We need a wiki page that  explains
> > how a person could get docs, etc. We already have a write-up but I
> > doubt many people will be able to find it (move it to support)
> >
> > >  From the contributing person point of view, we should have maybe modify
> > > DocumentHowto to include some staged instructions for submitting:
> > > (this is a first proposed draft):
> >
> > Good idea
> >
> > >   Okay, You've just completed your amazing howto, document or a carfully
> > > crafted world domination plan and want to have it public?  What to do
> > > next you might ask? Follow this to make you stuff matter:
> > >
> > >     * Go to the /SubmittedPendingDocs wiki page, link your new page from
> > > there. If you made an HTML/DocBook or other format doc - then put it on
> > > the web somwehre, or upload it to the wiki so we can view it.
> > >    * Post the mailing list with "subject: [PEND_REVIEW] <link to your
> > > new doc>".
> > >    * be ready for some comments and discussion ;)
> >
bugzilla for this ? if possible see comments bellow

> > What we might do is moving stuff out of the wiki faster, so that the
> > wiki is mostly empty, but then, how do people update pages?
> > Or should we have duplicate pages, one in the wiki and one in support?
> I think moving it out of the wiki to the site is a good idea.  Than it
> would be easier to find.  Duplicate pages could work, but than we get a
> problem like on the old wiki with the faq where no one is updateing the
> real faq on the page.  I don't know how to handle this except have a
> couple people who's soul job is to make sure to keep the site updated
> from the wiki, does that sound good?
I think that wiki should only be for drafts - after it has been
approved as per sivangs proposal earlier (maybe this would be easier
if we had a bugzilla documenation product or similar - then do reviews
and super-reviews)

Once something has been formally accepted it needs to be moved from
the wiki into docbook on the svn server. (sorry but i haven't looked
into the ReST to docbook coverter yet will do in next few weeks - feel
free to takeover)

>From here it can be converted and put on the support page. Having it
in docbook on the svn server has several advantages one of which is we
can put it into yelp for the next release so people have everything
they need at thier fingertips and it reduces load on the slow wiki.


> >
> > These are just some thoughts I had, i agree with the overall idea, i
> > just do not yet see how we could make it work without (again) slowing
> > down contributors
> >
> > nice write-up sivang, greets AP
> Yes it was a very nice write-up.
> John
Yes good write up - these are definatley issue that need addressing
> >
> 
> 
> --
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc
> 
> 
> 
> 


-- 
<a href="http://spreadfirefox.com/community/?q=affiliates&id=82&t=1">Get
Firefox!</a>