couchdb-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Cottlehuber <d...@muse.net.nz>
Subject Re: Docs, second try
Date Tue, 31 Jul 2012 02:08:08 GMT
On 30 July 2012 18:41, Simon Metson <simon@cloudant.com> wrote:
> Hi,
> Has this moved on at all? Thinking about it a bit more (off and on)
> I'm inclined to suggest that DocBook isn't the greatest format. If
> we stored the docs in markdown it would be easier for people to
> edit/contribute (they could view the docs and make changes in
> github without having to compile/install anything). I'm happy to
> put some cycles into converting whats there to a bunch of
> markdown. Rendering that in futon is pretty easy too.
>
> I can see the benefits of DocBook for writing a book, but I'm not
> sure that its what's needed here - it seems like using a hammer to
> crack a nut.
> Cheers
> Simon

+1. TL;DR:

Let's focus on the *real* issue: despite having a great working base
for over 5 months now, the docs contribution barrier is too high for
even the dev community to make any progress.

I now have a working export of DocBook -> Markdown,  using Pandoc[1],
which can be turned into HTML5, PDFs or ePUBs easily.

Notes/results: https://gist.github.com/3212532#file_readme.md
If you want epub or PDF, try using this branch:
https://github.com/dch/couchdb/tree/docs

My next steps:

- check the details (in daytime)
- document how to add a chapter/section
- make a list of things to be added to reach 1.2.0 equivalence
- get stuck in & get helpers
- sort out CSS & images for futon & standalone viewing
- integrate build step with autotools
- get this into 1.3.0

Long Version:

Tonight, I tried to add a simple section to the XML pages, explaining the new
[vendor] field in default.ini. I gave up after an hour of faffing about.

If I'm not able to drive it, we set the contribution barrier too high methinks.

I then tried installing XML editors and trying to make sense
of the admittedly awesome couchbase doc structure, and related
tools. I still failed, I was unable to add a simple chapter, or clarify
the new [vendor] section in default.ini.

Clearly somebody who *knows* DocBook and XML will be annoyed
at my incompetence, but so far none of those people have the time
to move our docs along, and more importantly, nor do most of our
contributors. I want this in 1.3.0, as a solid baseline for the next
release with bigcouch included.

The output is not yet perfect, but I believe its workable:

- the structure is right (chapters, headings, links, code)
- integrating small sections works (merge chapters -> larger doc)
- images are missing (I was too lazy to copy them in)
- some tables are not right yet (ditto)
- I don't have CSS right (ditto)

Let's do the conversion, get the docs into master, and get them
updated for 1.3. I'm up for it & I'm not waiting for DocBook nirvana
to arrive, because the current barrier to contribution is simply too high.

Pandoc[1], is a GPL-licensed Haskell library. It's available as a binary
on pretty much every system we dev on, either in package manager tools
or via download. And it just works, surprisingly well too, and it's
fricking FAST. Blazing. DocBook -> HTML5 in seconds, without
installing FOP, 6 jars, 12 perl modules, and the kitchen sink.

Let's get this off the ground. Please.

A+
Dave

[1]: http://johnmacfarlane.net/pandoc/

Mime
View raw message