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

[Joe Julian]

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?

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.gluster.org/pipermail/gluster-infra/attachments/20150109/a6c693d1/attachment.html>