[Nitro] New Blog Article About Nitro/Og

Robert Mela rob at robmela.com
Fri Oct 26 12:41:59 EDT 2007


The really hard part of cheatsheets is gathering, verifying, and 
organizing the content.   Especially keeping it neat and simple enough 
to be scanned and understood quickly, be quick as a quick ref, and yet 
no so dumbed down as to be useless after the first scan.

The quantity of content, if and when they're finished, will be small 
enough that cconverting to this or that markup should only take a few 
hours to a day.   I found that agonizing over choice of markup was 
preventing me from actually getting started.  I think too that having 
some actual content makes the choice and implementation of markup much 
simpler.

That said, they can live in any markup form.  I've thought about 
docbook, since that makes them easier to organize, and from docbook one 
could generate markup, html, or whatever.  

I think cheatsheet content could be distributed among source code files 
-- and indeed it is, as some is lifted directly from George's 
comments.    But the limitation of, say, RDoc, is that it would not be 
possible to achieve the right flow for a quick-scan tutorial and 
centralized quickref.

I see cheatsheets as necessarily being less comprehensive than the RDocs.

Thomas Leitner wrote:
> How about a system like the one used by the Django framework? They  
> have all the necessary user documentation as text files in the  
> repository. It seems quite reasonable to have the documentation in  
> the source code repository and using a markup language like Markdown  
> or Textile would make it easy to read the docu as plain text and as  
> HTML (I personally prefer Markdown with extras - see http:// 
> maruku.rubyforge.org). This would be usage documentation in contrast  
> to the API documentation provided by the RDocs.
>
> An additional wiki where users could post documentation, tips and  
> tricks wouldn't be bad either, perhaps integrate oxywtf better into  
> the documentation effort.
>
> Just some thoughts because I currently don't have time to provide  
> anything else.
>
> Thomas
>
> On 26.10.2007, at 17:48, Robert Mela wrote:
>
>   
>> I'd love to see the site code so I can learn yet more about Nitro.
>>
>> I'd be happy to move cheatsheets over to nitroproject.org, and  
>> certainly seeing how George and others code in Nitro will give me  
>> more stuff to fold into the cheatsheet docs.   It'd also be a great  
>> way for users on this list to learn each others idioms.   Best  
>> techniques for using Nitro, based on experience, would soon follow.
>>
>> This framework is just too wonderful to let wither.
>>     
>
> _______________________________________________
> Nitro-general mailing list
> Nitro-general at rubyforge.org
> http://rubyforge.org/mailman/listinfo/nitro-general
>
>
>   

-------------- next part --------------
A non-text attachment was scrubbed...
Name: rob.vcf
Type: text/x-vcard
Size: 116 bytes
Desc: not available
Url : http://rubyforge.org/pipermail/nitro-general/attachments/20071026/e6cab3af/attachment.vcf 


More information about the Nitro-general mailing list