[Nitro] New Blog Article About Nitro/Og
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
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
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.
> 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
-------------- next part --------------
A non-text attachment was scrubbed...
Size: 116 bytes
Desc: not available
Url : http://rubyforge.org/pipermail/nitro-general/attachments/20071026/e6cab3af/attachment.vcf
More information about the Nitro-general