Proposal to change Wiki/Doc process

[Jacques Nadeau <ja...@apache.org>]

Hey Guys,

I'd like to give a shoutout to Bridget and Bob for putting together a bunch
of great documentation.  You may not have noticed but they've generate a
bunch of great content.  However, it suffers from sitting over on our
Confluence wiki for a few reasons:

- doesn't look like Drill website/Drill content proper
- Google can't tell as well that this portion of the Apache Wiki is focused
on Drill (hurts SEO)
- Is confined to a template that has too much chrome and not enough
content.
- Hard to find. (as opposed to say drill.apache.org/docs)
- No simple way to tag entire docs tree to their version for a particular
release
- Secondary process for managing contribution and permissions
- Users have to get permission before they can start editing anything
- No change tracking to make sure that doc updates are correct.

As such, Tomer, Kirstine Hahn (new doc person) and Bridget have been
working on migrating over to using markdown, github and jekyll to manage
the documentation pages. This is exactly how the Drill website is now
managed.  With this model, we can manage code and documentation
contributions using the same mechanisms.  Since we're using jekyll &
markdown, it also means you can just fork the documentation and edit it
using github's built in markdown editing tools.  While markdown may not be
the most advanced system in the world, I think it becoming the standard due
to its simplicity.

You can see the current iteration at [1] and the source is at [2].  There
are three big things that we need to fix, an omnipresent left nav, anchor
links on titles and omnipresent one click link to fork a file similar to
[3]. (For this third one, we should just add this across the site).  Once
these are complete I propose deprecating the wiki and moving to everything
being managed in git.  As part of this, we'll also need to put together a
doc page that talks about how someone can contribute to the docs.

Thoughts?

Jacques

[1] http://apache.github.io/drill/docs/
[2] https://github.com/apache/drill/tree/gh-pages/_docs
[3]
https://github.com/apache/drill/edit/gh-pages/_docs/drill-docs/001-arch.md

Re: Proposal to change Wiki/Doc process

[Michael Hausenblas <mi...@gmail.com>]

> Confluence is nice, but it really doesn't fit here for all the reasons you say

+1 for moving over to the new process.


> Also, the Apache instance is dog slow.

That, dear Ted, is an insult for pretty much any dog, out there ;)


Cheers,
	    Michael

--
Michael Hausenblas
http://mhausenblas.info 

> On 29Jan2015, at 17:23, Ted Dunning <te...@gmail.com> wrote:
> 
> On Thu, Jan 29, 2015 at 12:21 PM, Jacques Nadeau <ja...@apache.org> wrote:
> 
>> Once
>> these are complete I propose deprecating the wiki and moving to everything
>> being managed in git.
>> 
> 
> +1
> 
> Confluence is nice, but it really doesn't fit here for all the reasons you
> say.  Also, the Apache instance is dog slow.

Re: Proposal to change Wiki/Doc process

[Ted Dunning <te...@gmail.com>]

On Thu, Jan 29, 2015 at 12:21 PM, Jacques Nadeau <ja...@apache.org> wrote:

> Once
> these are complete I propose deprecating the wiki and moving to everything
> being managed in git.
>

+1

Confluence is nice, but it really doesn't fit here for all the reasons you
say.  Also, the Apache instance is dog slow.