Documenting Ruby 1.9: Ebook or Wiki?

[Run Paint Run Run]

I'm writing a free ebook about Ruby 1.9 at http://ruby.runpaint.org/ .
I intend for the first release to coincide with that of Ruby 1.9.2,
which gives me just under two months to get it into a reasonable
state. (I realise it's far from that currently).

However, the more I write and plan, I wonder whether the community
would prefer this as a wiki. I'd still write the bulk of the content,
and continue to store it in Git. Markdown would be used for editing.

So, what's the consensus?

 

[Mohit Sindhwani]

I'm writing a free ebook about Ruby 1.9 at http://ruby.runpaint.org/ .
I intend for the first release to coincide with that of Ruby 1.9.2,
which gives me just under two months to get it into a reasonable
state. (I realise it's far from that currently).

However, the more I write and plan, I wonder whether the community
would prefer this as a wiki. I'd still write the bulk of the content,
and continue to store it in Git. Markdown would be used for editing.

So, what's the consensus?

I'd say wiki - if it's in Markdown or Textile, it could be easy enough
to wget everything and make it an acceptable PDF/ e-book style file
every now and then?

Cheers,
Mohit.
4/6/2010 | 11:37 AM.

 

[botp]

I'd say wiki - if it's in Markdown or Textile, it could be easy enough to

+1

 

[Run Paint Run Run]

I'd say wiki - if it's in Markdown or Textile, it could be easy enough to

wget everything and make it an acceptable PDF/ e-book style file every now
and then?

Not really. They're quite distinct styles. An offline wiki is trivial,
certainly, but it won't have the structure and coherency of a book.

 

[Mohit Sindhwani]

Not really. They're quite distinct styles. An offline wiki is trivial,
certainly, but it won't have the structure and coherency of a book.

Of course, you're the project owner so you know best...
But, I'm of the opinion that even in a wiki, we could have a table of
contents that would map roughly to chapters and sections so that the
coherency is maintained. Someone would need to help to keep the
contents categorized into a hierarchy (something that books demand and
wikis ignore) such that it is coherent.

I guess I'm really pushing for an "editable" e-book... that said, since
the source is in git and Markdown (I wish it could be TexTile), changes
can be made at source though the barrier is slightly higher..

Cheers,
Mohit.
4/6/2010 | 12:16 PM.

 

[Stuart Ellis]

=20
Of course, you're the project owner so you know best...
But, I'm of the opinion that even in a wiki, we could have a table of =

contents that would map roughly to chapters and sections so that the =
coherency is maintained. Someone would need to help to keep the =
contents categorized into a hierarchy (something that books demand and =
wikis ignore) such that it is coherent.

=20
I guess I'm really pushing for an "editable" e-book... that said, =

since the source is in git and Markdown (I wish it could be TexTile), =
changes can be made at source though the barrier is slightly higher..

=20
Cheers,
Mohit.
4/6/2010 | 12:16 PM.
=20

-1 to Wiki. I was on a project that tried the idea of developing larger =
documents with a Wiki, and it just sucked. Wiki UIs are mainly designed =
for short bits of text, so you end up copying text into an editor, and =
then double-checking that the page hadn't been edited, and then pasting =
it back. Edits are often of low quality, one way or another, and need =
either fact-checking or revision to integrate them into the text to keep =
it coherent, which is tedious.

 

[Run Paint Run Run]

In the absence of a consensus, I suppose I'll keep to this kind of
format ( http://ruby.runpaint.org/methods ) for now. Maybe if interest
picks up subsequently, I'll look at making the chapters editable
similar to what Mohit suggested.

 

[Robert Klemme]

In the absence of a consensus, I suppose I'll keep to this kind of
format ( http://ruby.runpaint.org/methods ) for now. Maybe if interest
picks up subsequently, I'll look at making the chapters editable
similar to what Mohit suggested.

Thanks for your effort! Since you said you are writing a book I
assume you have particular kinds of readers in mind and will give it a
flow so it can be reasonably read from start to end. I don't think a
Wiki is a good container for something like that. If you want to
allow for user added content then it's probably best to have some kind
of commenting functionality (as they do for PostgreSQL documentation,
see http://www.postgresql.org/docs/).

Kind regards

robert

 

[botp]

Thanks for your effort! =A0Since you said you are writing a book I
assume you have particular kinds of readers in mind and will give it a
flow so it can be reasonably read from start to end. =A0I don't think a
Wiki is a good container for something like that. =A0If you want to
allow for user added content then it's probably best to have some kind
of commenting functionality (as they do for PostgreSQL documentation,
see http://www.postgresql.org/docs/).

i think you can add comment feature in wikis.
btw, it would be also nice to include a ruby-format (besides plain
markdown/textile) so as to allow nice/uniformed ruby code formatting
...

kind regards -botp

 

[mdiam]

Not really. They're quite distinct styles. An offline wiki is trivial,
certainly, but it won't have the structure and coherency of a book.

+1 for wiki

With the wiki data (e.g; in Markdown format) you could manually
build (impose) the structure of the book, then use ruby to process
the different chapter from the markdown to any other format
(i.e. via LaTeX or ConTeXt).

The advantages are:
- produce high quality pdf document (thank to TeX),
- allow to automatically produce other output format
(immediate html output),
- allow to let someone else translate the book to foreign languages

For sample, the jelix book (a php framework) is automatically
generated to pdf from a dokuwiki to xml docbook, then LaTeX.
the pdf.

http://download.jelix.org/jelix/documentation/en

-- Maurice

 

[Robert Klemme]

i think you can add comment feature in wikis.

Yes, but a Wiki is organized as a hypertext and not as a sequential
text. That was my main point.

Cheers

robert

 

[Roger Pack]

So, what's the consensus?

My own preference would be to "enhance" the existing Wikibook

http://en.wikibooks.org/wiki/Ruby_Programming

I've also heard good things about docuwiki, though never used it (and
who needs offline access these days? Only a very small percentage of
ruby developers' time is spent offline, I'd imagine...)
-rp

 

[botp]

http://en.wikibooks.org/wiki/Ruby_Programming

i didn't noticed that. thanks for the link.
kind regards -botp

 

[Sora Harakami]

+1 for editable "e-book".
and I thought following:
* Can download ebook (like epub, pdf, txt, markdown, etc...).
* Can see by wiki system
* Make snapshot book release
* And make editable by wiki

 

[Mohit Sindhwani]

-1 to Wiki. I was on a project that tried the idea of developing larger documents with a Wiki, and it just sucked. Wiki UIs are mainly designed for short bits of text, so you end up copying text into an editor, and then double-checking that the page hadn't been edited, and then pasting it back. Edits are often of low quality, one way or another, and need either fact-checking or revision to integrate them into the text to keep it coherent, which is tedious.

How about a book in something like Radiant with comments enabled to
gather feedback?

Cheers,
Mohit.
6/6/2010 | 6:08 PM.

 

[Stuart Ellis]

of contents that would map roughly to chapters and sections so that the =
coherency is maintained. Someone would need to help to keep the =
contents categorized into a hierarchy (something that books demand and =
wikis ignore) such that it is coherent.since the source is in git and Markdown (I wish it could be TexTile), =
changes can be made at source though the barrier is slightly higher..larger documents with a Wiki, and it just sucked. Wiki UIs are mainly =
designed for short bits of text, so you end up copying text into an =
editor, and then double-checking that the page hadn't been edited, and =
then pasting it back. Edits are often of low quality, one way or =
another, and need either fact-checking or revision to integrate them =
into the text to keep it coherent, which is tedious.

=20
How about a book in something like Radiant with comments enabled to =

gather feedback?


I think that is a good idea. I''ve now looked through the text, and =
well, wow, it's a complete draft of a book. It's got a particular style =
throughout the writing, so fitting casual edits or third-party patches =
into the text would be hard.

 

[Roger Pack]

My own preference would be to "enhance" the existing Wikibook

http://en.wikibooks.org/wiki/Ruby_Programming

I could sure use some help with editing the wikibook (wink, nudge)...
-r