Rob,<br><br> This is similar to something I mentioned awhile back. And it has one particular issue. The documentation does not evolve and get transported to users when they do, say... "sudo gem install og --version=
0.40.0" or however you would type this for a specific version. (don't feel like looking it up) Including og and nitro documentation in rdoc along with the code accomplishes your goal and it keeps all evolving changes to documentation with the pertinent code. Tutorials should be a part of the rdoc documentation is what I'm saying. Oxyliquit provides a place for users to post tutorial ideas and the base ones, like your cheatsheets get installed with every gem.
<br><br> As for the collaborative documentation aspect, I'll have to think about that for a bit. The back of my head is screaming wiki with an automated export into darcs that only george can kick off. I'll post back when I have some more defined ideas.
<br><br> I would be willing to post an example of what I propose to this list
for you guys to consider. I know this doesn't necessarily associate
the comment threads like on the php docs site you mentioned, I'd have to put
more thought into that than I have available brain power currently.<br><br>Just my 2cents<br><br>Chris<br><br>Below is the comment I made a while back about documentation called "Keeping Documentation and Tutorials up-to-date"
<span style="font-size: larger;"></span><br><br><blockquote style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 6.8ex; padding-left: 1ex;" class="gmail_quote">
Hi all,<br><br> A methodology recommendation has been rolling around
in my head for a few days now and I'd like to bring it up here on the
mailing list. So, I'll get started with a little background and a
question.
<br><br> I was reading a post earlier today called "The basics" and
want to ask the question "Where are the new tutorials going to be
published?".<br><br> This seemed like an innocent enough question until i realized, your probably going to put it on
<a href="http://oxywtf.de/" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">OxyLiquit</a>.
I'm not going to knock putting them there, it's actually one of the top
locations new users are going to look for that information. The
problem I see is the same thing that happened to the other 4 tutorials.
<br><br> They went out of date almost as quickly as they were posted.<br><br>
I would like to make a recommendation to the Nitro/Og (raw, etc, etc.)
team. How about rolling a basic tutorial into the RDocs. IMHO the
situation your team is running into is a knowledge transfer gap between
the creators and the intermediate to expert users of Nitro, not the
newbies who barely know where to start. <a href="http://rake.rubyforge.org/" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">Rake's RDoc index page</a>
is a good example of what I think Nitro's should look like. It gives
all the information a newbie needs to get their feet wet and attempt to
get to an intermediate level of understanding.
<br><br> What the expert users needs is good reference material that
explains the inner workings of how the components work with each other
and small examples of how someone can utilize them. eg: <a href="http://rake.rubyforge.org/classes/Rake/RDocTask.html" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">
Rake::RDocTask</a> and <a href="http://rake.rubyforge.org/classes/Rake/GemPackageTask.html" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">Rake::GemPackageTask</a>
These examples do not need to be easily understood by a novice.
However, they do need to effectively communicate a technical concept to
a competent ruby developer without having to delve too deeply into the
code to accomplish something. I'm not saying they won't run into
exceptions trying to get it working, but they should know what is
possible with the class or module.
<br><br>note: I used rake just because it's something I picked up fairly quickly due to the rdocs.<br><br>
The advantage of taking this approach to documenting your projects is
you create a basis for the expert users to write the tutorials. They
could write them on their blogs, (good for your google ranking), on
Fora or on OxyLiquit. I'm basically saying, you should not be writing
full blown tutorials, but moving smaller examples of how to perform
actions into your RDocs. This has key advantages...
<br><br>1 - When a developer makes a change to the code they can make the example adjustments without having to open another editor.<br>
eg: Or even better, without having to open a web browser, login to a
wiki ( whatever ) and then make changes. Way too many steps.
Developers are lazy, I mean efficient. (tongue in cheek)
<br>2 - The examples for a particular version of each project are in revision control with the code they reference.<br> eg: someone can download x.x lower version of the project and have the correct examples for that version
<br>3 - The published RDocs can be available through your website and
through ri without you having to publish yet another piece of
documentation.<br> eg: rake deploy is all it takes (if you use newgem, not sure if you do)
<br>4 - Patches from your userbase don't have to be just code, they can be updates to your tutorials as well.<br>
eg: In fact if I were in your shoes, the first page of the RDocs would
reference a page on how to submit updates to the examples as a patch.
<br><br> As a final note, I would like to say the HelloWorld example from the repository for nitro-0.50
is a perfect starting point to put in the RDocs. Then you could work
the Blog example in for each of the components you want to communicate
howto ___. I'm all done ranting.
<br><br>Criticism always welcome,<br><br>Chris Scheper<br></blockquote><br><div><span class="gmail_quote">On 10/3/07, <b class="gmail_sendername">Robert Mela</b> <<a href="mailto:rob@robmela.com" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">
rob@robmela.com</a>> wrote:
</span><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">Sorry... I misunderstood the question... I'm up to my eyeballs in<br>exploring Og right now, and its filtering everything I see. I look at
<br>my wife and kids and visualize the generated foreign key attributes that<br>join us.... :)<br><br>Thanks for the kudos. What I'd like more than my cheatsheets is a<br>collaborative effort to produce documentation similar to the PHP docs --
<br> <a href="http://www.php.net/docs.php" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">http://www.php.net/docs.php</a>. I see it as a nitro app, with content<br>in DocBook or something similar. Perhaps Nitro elements could be
<br>created named similarly to DocBook elements, such that the docbook pages
<br>can be served up directly, as-is. The same pages could be used later<br>to generate a print book -- produced by a community(!) with proceeds<br>going back to the project.<br><br>Would someone be willing to host that in a mercurial or darcs archive?
<br><br>thx.<br><br>Robert Mela wrote:<br>> Some of the relation declarations are for the benefit of Og in schema<br>> generation.<br>><br>> Others are for the benefit of Forms in generating form elements to<br>
> bind relations ( see the views in nitro/part/admin/og )<br>><br>> Arne Brasseur wrote:<br>>><br>>> G, is this known/intended? If so it should be documented. Robert, you<br>>> could perhaps add this to your cheatsheets? Very nice work BTW! I'm
<br>>> using them all the time now.<br>>><br>>> <a href="http://robmela.com/cheatsheets" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">http://robmela.com/cheatsheets</a><br>>>
<br>>> (ab)<br>>><br>>><br>><br>> _______________________________________________
<br>> Nitro-general mailing list<br>> <a href="mailto:Nitro-general@rubyforge.org" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">Nitro-general@rubyforge.org</a><br>> <a href="http://rubyforge.org/mailman/listinfo/nitro-general" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">
http://rubyforge.org/mailman/listinfo/nitro-general
</a><br><br><br>_______________________________________________<br>Nitro-general mailing list<br><a href="mailto:Nitro-general@rubyforge.org" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">Nitro-general@rubyforge.org
</a><br><a href="http://rubyforge.org/mailman/listinfo/nitro-general" target="_blank" onclick="return top.js.OpenExtLink(window,event,this)">
http://rubyforge.org/mailman/listinfo/nitro-general</a><br><br></blockquote></div><br>