[Gluster-infra] Where's the documentation source?

[Michael Scherer]

Le vendredi 09 janvier 2015 à 09:56 -0800, Joe Julian a écrit :
> 
> On 01/09/2015 06:06 AM, Tuomas Kuosmanen wrote:
> 
> > ----- Original Message -----
> > > From: "Joe Julian" <joe at julianfamily.org>
> > > This page has broken links:
> > > http://www.gluster.org/documentation/Getting_started_overview/
> > > 
> > > The unbroken links don't have their respective source in
> > > https://forge.gluster.org/gluster-site/gluster-site
> > The docs are pulled in from https://forge.gluster.org/gluster-docs-project 
> > as far as I know. The main site is set up to automatically sync from git,
> > but the docs are not yet. And actually I am a bit uncertain on what to do.
> > Maybe this is a good spot to discuss this:
> > 
> > I need to know more about how the documentation is written and maintained. 
> > There seems to be a substantial amount of docs in the wiki. And my understanding
> > is that quite a lot of people just use the wiki docs when they need information. 
> > Am I correct? Also, how up to date / sensible is the documentation under 
> > http://www.gluster.org/documentation/ ?
> > 
> > There also seems to be a consensus to keep the wiki around, and even make it
> > more central in the community (wiki.gluster.org or gluster.org/wiki/ or
> > such and use it for planning and other things.
> > 
> > What if we do these things with the docs:
> > 
> >   1. Revise the "getting started" documentation so that it is in good shape to
> >      get new people started. Have it under gluster.org/download/. The goal would
> >      be that a newbie has a functional Gluster setup after following the instructions.
> > 
> >   2. All in-depth, more advanced documentation could be in the wiki, and certain
> >      sections would be linked from the "getting started" instructions too, since
> >      there are many different ways you can install and use gluster.
> > 
> > Would this make sense? If so, maybe we should just focus in moving the other docs
> > into the wiki, and review the install+setup guide to have a good howto to get started.
> > 
> > Maybe we should have a new mediawiki setup and then move stuff over, link to it once we
> > have the docs in sensible state there?
> > 
> > //Tuomas
> > 
> So, there's the docs in the source tree,
> https://forge.gluster.org/gluster-docs-project, the wiki, and some
> docs in https://forge.gluster.org/gluster-site/gluster-site.
> 
> The devs are supposed to update the docs in the source tree when they
> make a change to the software (last I heard).
> 
> There's a few Red Hat people and several spammers contributing to
> gluster-docs-project. Looks like it's driven by osas and is owned
> exclusively by Red Hat, copyright and all rights reserved with no
> license to the contrary.
> 
> Michael says the docs in gluster-site are an accident. Looks like that
> directory needs to be added to .gitignore?

I was speaking of the oldlayout and documentation folder in gluster-doc.
One of them need to go, not sure which. And it doesn't completely build,
IIRC.

But yeah, there is also the fact there is documentation in gluster-site.

The layout of the complete website is a bit messy, to say the least. We
have all application using some specific url, that are referenced
everywhere, etc.

> The wiki works for sysadmins that are not devs. Everyone knows how to
> type something into a box and hit submit.
> 
> Nobody from outside Red Hat is offering anything since this whole push
> to leave the wiki behind was started. With documentation spread all
> over the place, nobody can (a) figure out which docs are relevant and
> (b) figure out how to report/submit a change. I'm consistently having
> people pop in to IRC to report a bug in one form of documentation or
> another, or asking about arcane deprecated uses from the wiki. I don't
> care which one we use, but can we please settle on just one.

Yeah, we should. i was looking at making the doc auto updated, but it
need clarity.

-- 
Michael Scherer
Open Source and Standards, Sysadmin
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: This is a digitally signed message part
URL: <http://www.gluster.org/pipermail/gluster-infra/attachments/20150109/45dc7491/attachment.sig>