On Oct 6, 8:21 am, Robert M. [email protected] wrote:
Sounds like there’s a consensus. I’ll start reading up on RDocs.
It might also make sense to coordinate on separate aspects of Nitro for
the first pass. I’m finding that learning Nitro and Og while
documenting the experience leaves coverage thin and incomplete. With
what little time I have it would take a to really learn and document Nitro.
It also makes it easier for each of us to take the role of newbie and
step through each others’ documentation, encountering the errors or
missing pieces just as a new user would.
Actually I would argue against RDocs as the primary documentation.
RDocs have some issues. The most overarching one is the need to write
code to fit docs rather than the other way around. RDocs are really
“programmer docs” not “user docs”.
I’m preparing to put together a Wiki for Facets Documentation (thanks
to these Nitro tutorials btw, I can finally see how to proceed!).
However, rather then use a simple flat-file system, I’m going to use a
DB and index the documentation by class/module, method, arity, and
more. This DB will be the official user documentation (and the RDocs
will just be for the programmer’s). It will be interesting to see how
that builds up over time, and what can be done with the DB, say to
generate a reference manual.
Perhaps we can work together to create a system we can all use, Nitro,
Facets or any other project too.
P.S. Isn’t require ‘nitro_and_og’ redundant now? Shouldn’t it become:
is the same as: