What for a Documentation Tool (WAS -> Re: HBase Hackathon IV Wrap-up)

[Stack <st...@duboce.net>]

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 <st...@outerthought.org> wrote:
> On Wed, Jul 14, 2010 at 1:20 AM, Stack <st...@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

Re: What for a Documentation Tool (WAS -> Re: HBase Hackathon IV Wrap-up)

[Steven Noels <st...@outerthought.org>]

On Wed, Jul 14, 2010 at 6:57 PM, Stack <st...@duboce.net> wrote:

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)?
>


Yep, Daisy can do all that and more, maybe we should look into an alarm
clock extension as well. :)


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.
>


Maybe we can come back to this when we have more resources to donate, in the
sense of actual people contributing to the documentation. I'm sure there's
still value in taking on Daisy but as you say, it's mostly all or nothing,
and even though the WYSIWYG authoring helps for being productive, it's not
easily integrated in an offline dev toolchain.

Cheers,

Steven.
-- 
Steven Noels                            http://outerthought.org/
Open Source Content Applications
Makers of Kauri, Daisy CMS and Lily

Re: What for a Documentation Tool (WAS -> Re: HBase Hackathon IV Wrap-up)

[Paul Smith <ps...@aconex.com>]

> 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.

As stack said, it'd be nice to have the documentation as part of the Maven build, this way it would be simple for any one to git clone, make edits available and sort of crowd-source it.

I had no idea there was so many 'docbook-like' things out there though.  Asciidoc looks nice.  Honestly as long as the presentation code is kept way out of the content you should start with something simple, and change it later.  there isn't an maven-asciidoc plugin I can find, but a simple execution path could be made to happen linked to a profile so as to only invoke the generation if you need it.

I would certainly like to volunteer some time to help with this, but I agree, since you want to reduce the barriers to entry, simplicity has to be one of the top criteria.

Paul

RE: What for a Documentation Tool (WAS -> Re: HBase Hackathon IV Wrap-up)

[Jonathan Gray <jg...@facebook.com>]

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
> <st...@outerthought.org> wrote:
> > On Wed, Jul 14, 2010 at 1:20 AM, Stack <st...@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