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? 
On 4/6/2010 11:30 AM, Run Paint Run R. wrote:
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.
On Fri, Jun 4, 2010 at 11:37 AM, Mohit S. [email protected]
wrote:
I’d say wiki - if it’s in Markdown or Textile, it could be easy enough to
+1
On 4/6/2010 11:55 AM, Run Paint Run R. wrote:
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.
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.
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.
On 4 Jun 2010, at 05:17, Mohit S. wrote:
Of course, you’re the project owner
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.
-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.
Stuart E.
[email protected]
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.
2010/6/4 Run Paint Run R. [email protected]:
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 PostgreSQL: Documentation).
Kind regards
robert
On Fri, Jun 4, 2010 at 8:57 PM, Robert K.
[email protected] wrote:
allow for user added content then it’s probably best to have some kind
of commenting functionality (as they do for PostgreSQL documentation,
see PostgreSQL: Documentation).
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
On Jun 4, 5:55 am, Run Paint Run R. [email protected] wrote:
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.
+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:
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
On 04.06.2010 15:22, botp wrote:
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 PostgreSQL: Documentation).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
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
On Sat, Jun 5, 2010 at 6:12 AM, Roger P. [email protected]
wrote:
i didn’t noticed that. thanks for the link.
kind regards -botp
+1 for editable “e-book”.
and I thought following:
On 6 Jun 2010, at 11:08, Mohit S. wrote:
Cheers,
Mohit.
4/6/2010 | 12:16 PM.-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?
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.
Stuart E.
[email protected]
On 4/6/2010 3:21 PM, Stuart E. wrote:
Not really. They’re quite distinct styles. An offline wiki is trivial,
Cheers,
Mohit.
4/6/2010 | 12:16 PM.-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.
My own preference would be to “enhance” the existing Wikibook
I could sure use some help with editing the wikibook (wink, nudge)…
-r
This forum is not affiliated to the Ruby language, Ruby on Rails framework, nor any Ruby applications discussed here.
Sponsor our Newsletter | Privacy Policy | Terms of Service | Remote Ruby Jobs