hbase-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jonathan Gray <jg...@facebook.com>
Subject RE: What for a Documentation Tool (WAS -> Re: HBase Hackathon IV Wrap-up)
Date Wed, 14 Jul 2010 17:28:08 GMT
Simple and effective.

I think now is not the time to adopt something that does any big sweeping change like change
our wiki, website, etc...

Let's just add something to our current basket of tricks that allows us to write clean and
effective "books" of versioned documentation that can be packaged into releases and available
online.

Emphasis on having a low barrier to entry and not putting any fear into eyes of devs.

JG

> -----Original Message-----
> From: saint.ack@gmail.com [mailto:saint.ack@gmail.com] On Behalf Of
> Stack
> Sent: Wednesday, July 14, 2010 9:58 AM
> To: dev@hbase.apache.org
> Subject: What for a Documentation Tool (WAS -> Re: HBase Hackathon IV
> Wrap-up)
> 
> Looking more, is it fair to say that using daisy just for
> documentation, going to an extreme, is a little like using a laptop
> for an alarm clock?  A laptop makes for a perfectly good alarm clock,
> but its not what you'd primarily use it for.  Daisy can be used as a
> documentation system, but to extract the most value of a daisy
> install, it should be serving hbase.org (or at least the wiki part of
> hbase.org)?
> 
> More below...
> 
> On Tue, Jul 13, 2010 at 10:39 PM, Steven Noels
> <stevenn@outerthought.org> wrote:
> > On Wed, Jul 14, 2010 at 1:20 AM, Stack <stack@duboce.net> wrote:
> >> That fellas have to put up a webapp container to author to write
> docs
> >> is too high a barrier in my opinion (I have to have a mysql running
> >> too?).  Getting fellas writing doc. is like pulling teeth at the
> best
> >> of times so barriers should be at a minimum.
> >>
> >> How would versioning work?  We'd have to pull out of daisy and
> commit
> >> into the repo?
> >>
> >
> >
> > People would access a centrally-hosted instance of Daisy to
> author/maintain
> > docs. Offline editing is impossible.
> >
> 
> Ok.
> 
> The hbase wiki and site are maintained by Apache.  If we put up a
> Daisy instance, we'd have to maintain it ourselves.  Maven generates
> our site for us.
> 
> 
> > Upon designated moments, we can then use the Books feature of Daisy
> to pull
> > a static copy from the webapp into the ASF repo - I'd say close to
> major
> > releases.
> >
> 
> Ok.
> 
> > There's a bit of work involved in setting up something which appeals
> both
> > visually and structurally to documentation authors - but nothing to
> be
> > afraid of. With the holiday season approaching however, doing so
> might take
> > until late August. If that's still helpful, we can look into helping
> out.
> >
> > With regards to physical provisioning of such a box, we don't have
> any
> > leftover capacity at the moment. Either we ask Apache (one of the Sun
> zones
> > boxes perhaps), or we investigate spare capacity somewhere else. We
> don't
> > have any internal hosting capacity to speak of, I suspect other HBase
> users
> > have that readily available. If that's not possible, it's a matter of
> hiring
> > a VPS somewhere out there and pointing docs.hbase.org to it.
> >
> Sounds like Jon could get us a box and we could run an experiment to
> see how people liked daisy-for-documentation.
> 
> My thing is that, like yourselves, we (hbase dev) have limited
> resources to devote to the doc project.  For me, choosing something
> like docbook -- a 'standard', a docsystem I and others already 'know'
> that has good integration with our maven build system -- seems like
> less work overall.
> 
> What do others thing?
> 
> St.Ack

Mime
View raw message