drill-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jacques Nadeau <jacq...@apache.org>
Subject Proposal to change Wiki/Doc process
Date Thu, 29 Jan 2015 17:21:51 GMT
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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message