From: Stuart Ellis <stuart@...>
Date: 2010-06-06T19:41:45+09:00
Subject: Re: Documenting Ruby 1.9: Ebook or Wiki?


On 6 Jun 2010, at 11:08, Mohit Sindhwani wrote:

> On 4/6/2010 3:21 PM, Stuart Ellis wrote:
>> On 4 Jun 2010, at 05:17, Mohit Sindhwani wrote:
>> 
>>   
>>> On 4/6/2010 11:55 AM, Run Paint Run Run 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 :P 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.
>>> 
>>>     
>> -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 Ellis
stuart@stuartellis.eu