Rails - Jul 2005 - Thoughts on Second-Tier Documentation

In the course of this argument, keep in mind that I think Rails is 
making excellent progress in the development of documentation and 
community.  I am only trying to develop discussion of where we need to 
go next.

A consistent theme we are seeing on this list, I believe, is frustration 
caused by the lack of second-tier documentation.  So far we have...

-- the various tutorials which are generally a "first experience with 
rails" focus
-- the pragmatic book tutorial (excellent source for an interested novice)
-- the pragmatic book Rails documentation
-- the online API
-- the wiki
-- various scattered sources (blogs, mailing list archives, etc)
-- existing source code (Rails, Typo, etc)

Each of these sources, for the most part, is either for the beginner or 
the expert.  We need to build better bridges between the two.

I think the solutions look like:

-- real code commented with a focus on answering "why" rather than
"what"
-- design-pattern discussion
-- opportunities for peer review

Ideas for action:

-- A lot of material exists in the community blogs, the mail archives, 
and other source.  I think we need to focus more on aggregating the 
reusable content (examples, explanation).  I think this would be best 
accomplished in a blog & comment format.  Wiki''s are an awesome
idea,
but I think it is too chaotic for a community where the non-experts so 
greatly outnumber the experts.  We need concrete "articles" written to
the rails user without the evangelism.  We''re already believers!

-- A code site.  A place to post everything from snippets to sample 
programs.  Also, features to post code of your own to receive 
criticism.  As an intermediate user, it is easy to figure out if my code 
works by testing, but it is hard to tell where I am missing the 
Rails/Ruby way.  I would _love_ the opportunity for someone to glance at 
a view and make suggestions of what to move to the controller, or look 
at a controller and suggest reworks to the model.  These
"conversations"
would have immediate impact to the poster, foster concrete discussion of 
the issues at hand, and become a resource to new learners.

Ok, these are some first thoughts.

PS: I am home sick watching the "Great Outdoor Games."  This is some 
weird stuff.

-- 
Jeff Casimir

Teacher, Cesar Chavez Public Charter High School for Public Policy
Education Consultant, Electronic Frontier Foundation

Not to play my own fiddle, but no one has anything to say on this 
topic?  Can you hear me out there?

-Jeff

Jeff Casimir wrote:
> In the course of this argument, keep in mind that I think Rails is 
> making excellent progress in the development of documentation and 
> community.  I am only trying to develop discussion of where we need to 
> go next.
>
> A consistent theme we are seeing on this list, I believe, is 
> frustration caused by the lack of second-tier documentation.  So far 
> we have...
>
> -- the various tutorials which are generally a "first experience with 
> rails" focus
> -- the pragmatic book tutorial (excellent source for an interested 
> novice)
> -- the pragmatic book Rails documentation
> -- the online API
> -- the wiki
> -- various scattered sources (blogs, mailing list archives, etc)
> -- existing source code (Rails, Typo, etc)
>
> Each of these sources, for the most part, is either for the beginner 
> or the expert.  We need to build better bridges between the two.
>
> I think the solutions look like:
>
> -- real code commented with a focus on answering "why" rather
than "what"
> -- design-pattern discussion
> -- opportunities for peer review
>
> Ideas for action:
>
> -- A lot of material exists in the community blogs, the mail archives, 
> and other source.  I think we need to focus more on aggregating the 
> reusable content (examples, explanation).  I think this would be best 
> accomplished in a blog & comment format.  Wiki''s are an
awesome idea,
> but I think it is too chaotic for a community where the non-experts so 
> greatly outnumber the experts.  We need concrete "articles"
written to
> the rails user without the evangelism.  We''re already believers!
>
> -- A code site.  A place to post everything from snippets to sample 
> programs.  Also, features to post code of your own to receive 
> criticism.  As an intermediate user, it is easy to figure out if my 
> code works by testing, but it is hard to tell where I am missing the 
> Rails/Ruby way.  I would _love_ the opportunity for someone to glance 
> at a view and make suggestions of what to move to the controller, or 
> look at a controller and suggest reworks to the model.  These 
> "conversations" would have immediate impact to the poster, foster
> concrete discussion of the issues at hand, and become a resource to 
> new learners.
>
> Ok, these are some first thoughts.
>

I''m a relative noob, but I''ll chime in.

I think something akin to a function style setup ala php.net (to  
reference another discussion) would be beneficial. I also find the  
community to be very helpful in that case, however, better, or easier  
to locate, documentation would aid in that.

E.g. this afternoon i was trying to figure out how to sort a select  
tag pulled from a table and I was using a find style that was a few  
versions old, as I saw that was how it was done in a tutorial. e.g.

<%= select("element", "elementtype_id",
Elementtypes.find_all.collect
{|f| [ f.name, f.id ] }, { :include_blank => false } ) %>

My original problem was that I couldn''t find out how to sort by alpha  
order (more so where to call it in the string). A question post to  
the #rubyonrails channel garnered an answer and a "why are you using  
that old style?" question. I ended up with this:

<%= select("element", "elementtype_id", Elementtypes.find
(:all, :order => "name ASC").collect {|f| [ f.name, f.id ] },  
{ :include_blank => false } ) %>

Now, I realize the framework is undergoing radical changes on a  
version by version basis, and therefore, focusing on a comprehensive  
documentation system on a function by function level is difficult to  
maintain. But in the long run, I would like to see something like that.



On Jul 18, 2005, at 7:17 PM, Jeff Casimir wrote:
> Not to play my own fiddle, but no one has anything to say on this  
> topic?  Can you hear me out there?
--

John Athayde
bobo-8WfjrGkLNeNByuSxxbvQtw@public.gmane.org

Meticulous | www.meticulous.com (work)
Rotoscope | www.rotoscope.com (sound: rock band)
Boboroshi & Kynz | www.boboroshiandkynz.com (sound: electronic)
Personal Weblog | www.boboroshi.com (play)

"Those who would give up essential Liberty, to purchase a little
temporary Safety, deserve neither Liberty nor Safety."
          - Benjamin Franklin (1706-1790)
                        Reply of the Pennsylvania Assembly to the  
Governor
                                  November 11, 1755



_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

I agree with you John.  I think the framework, however, is now beyond a
point where we can accept putting things off.  Given the realitites of
publishing schedules for all these book authors, the need for code
stability to facilitate marketing, and the swell of new users that are
coming into the community, I would strongly suspect that we are entering
a phase where not much changes for awhile.

That overly-wordy bit being said, I think you''re right that we need to
start working on practical examples.  Your experience with the find
command was a perfect illustration.  Once you saw an example, I''m sure
it was pretty trivial.  The only way we can really build this content,
though, is through a widespread effort.  When things come up on the
mailing list or IRC and good solutions are found we have to record them
(wiki, railsdock, etc).  It''s not hard, but we can''t leave the
burden
to the experts.  It is usually the novice who has the best idea what
needs to be asked or answered.  We could do well to have "too much"
content and end up pulling down weak/less useful examples.

Let''s get there first.

-Jeff

John Athayde wrote:
> Now, I realize the framework is undergoing radical changes on a version by
> version basis, and therefore, focusing on a comprehensive documentation
> system on a function by function level is difficult to maintain. But in the
> long run, I would like to see something like that.

I think the documentation should facilitate all of this. I''m also a
firm believer that RDoc cannot handle the task set forth, and really
needs to be given up for some proper documentation.

Things I see vital in the documentation:

1. Explination of the method (bare-bones there)
2. Example calls of the method (very rare examples in the doc)
3. User comments
4. Search
5. Browse-ability

Those that say the current documentation is fine have obviously not
looked at it objectively. I think it''s fine for people intimately
familiar with Ruby and the Rails framework. Those not have a better
chance searching for a water bottle in hell. If anyone has ever used
php.net documentation, they know it''s a wonderful resource and nearly
finds things for you.

I''d love to help in this push if others are interested.  However some
serious planning is in order. I don''t think this is a
build-it-and-think-later thing. This involves some serious IA and
thought about the best way to display and organize the methods/classes
found in rails.

On 7/18/05, jeff-commontext-4tgruyIzQvrYtDzKz19aaEEOCMrvLtNR@public.gmane.org
<jeff-commontext-4tgruyIzQvrYtDzKz19aaEEOCMrvLtNR@public.gmane.org>
wrote:
> 
> I agree with you John.  I think the framework, however, is now beyond a
> point where we can accept putting things off.  Given the realitites of
> publishing schedules for all these book authors, the need for code
> stability to facilitate marketing, and the swell of new users that are
> coming into the community, I would strongly suspect that we are entering
> a phase where not much changes for awhile.
> 
> That overly-wordy bit being said, I think you''re right that we
need to
> start working on practical examples.  Your experience with the find
> command was a perfect illustration.  Once you saw an example, I''m
sure
> it was pretty trivial.  The only way we can really build this content,
> though, is through a widespread effort.  When things come up on the
> mailing list or IRC and good solutions are found we have to record them
> (wiki, railsdock, etc).  It''s not hard, but we can''t
leave the burden
> to the experts.  It is usually the novice who has the best idea what
> needs to be asked or answered.  We could do well to have "too
much"
> content and end up pulling down weak/less useful examples.
> 
> Let''s get there first.
> 
> -Jeff
> 
> John Athayde wrote:
> 
> > Now, I realize the framework is undergoing radical changes on a
version by > version basis, and therefore, focusing on a comprehensive
documentation
> > system on a function by function level is difficult to maintain. But
in the > long run, I would like to see something like that.
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
> 

-- 
Kyle Neath
kneath-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
http://www.neathdesign.com

Despite having tried to argue most of these points in another recent  
tread, I will chime in here as well, although I''m trying hard to not  
be known as a "one-trick" kind-of-guy ;-)

On 19 Jul 2005, at 08:16, Kyle Neath wrote:
> Things I see vital in the documentation:
>
> 1. Explination of the method (bare-bones there)
> 2. Example calls of the method (very rare examples in the doc)
> 3. User comments
> 4. Search
> 5. Browse-ability
Yes, to all of the above, but especially point 2.  Each method with  
multiple options/params should be shown using all those and what it  
will return as a result.

> Those that say the current documentation is fine have obviously not  
> looked at it objectively. I think it''s fine for people intimately
> familiar with Ruby and the Rails framework. Those not have a better  
> chance searching for a water bottle in hell. If anyone has ever  
> used php.net documentation, they know it''s a wonderful resource
and
> nearly finds things for you.
Yes, the PHP.net documentation should NOT be written off lightly, as  
it is AFIK the best of breed out there, that few others have even  
come close to matching. (If you know differently, I''d love to know  
about it including why that is the case)

So essentially, the Ruby/RoR community has a template to follow and  
improve upon when implementing this themselves.  The php.net template  
is imperfect at times, but those imperfections can easily be changed/ 
improved.

If you haven''t used PHP, or is somehow adverse towards it, forget  
about the language per se, and study the way they have provided and  
structured their documentation, and the way they have designed the  
presentation of it. You cannot fail to be impressed by it IMHO.

> I''d love to help in this push if others are interested.  However  
> some serious planning is in order. I don''t think this is a
build-it-
> and-think-later thing. This involves some serious IA and thought  
> about the best way to display and organize the methods/classes
> found in rails.
-- I think the documentation would by necessity need to encompass  
both Ruby and RoR, since without a Ruby reference most of the RoR  
stuff will make less sense. 

-- The php.net documentation already provides the essential framework  
(IA?) structure that should be followed, so there are only minor  
issues relating to naming conventions and where RoR should be within  
that structure left to address really. Just look at this ToC [ http:// 
www.php.net/manual/en/ ] and you will see a clear structure that  
works. (PHP''s slightly messy nature is not exactly helping them, but  
it still works logically)

-- As I wrote in this [ http://article.gmane.org/ 
gmane.comp.lang.ruby.rails/14904 ] response to Duane Johnson, each  
item of the documentation needs to be properly structured in order  
for it to be easily used in whatever way is wanted down the road. 

The current implementation of Raildock [ http:// 
raildock.mytechsupport.com/ ]  (I''m using Raildock as an example,  
since it''s current and the only one i know about) is a start, but it  
is also flawed in GUI terms, and I''m afraid of it being a dead end  
road full of wasted time and energy unless it''s corrected asap. OK,  
possibly strong words, but here''s the argument for that point of view.

Using the Raildock site to search for "link_to" [ http:// 
raildock.mytechsupport.com/ri/ 
ActionView::Helpers::UrlHelper@link_to ] returns a page that is  
containing information, but it''s not easily digestible by either  
humans or regexp.

-- It is visually difficult to read the information on that page, due  
to text colour, white space and information structuring issues. In  
other words it seems more like a republishing of available  
documentation rather than an attempt to re-invent a badly structured  
documentation.

-- The UI is functional, but the PHP manual beats it hands down.  
Select menus may save space, but reduces overview and context  
comprehension.

--  When looking at the relevant HTML code output this is how it  
looks like:

=begin code snippet
================<b>ActionView::Helpers::UrlHelper#link_to</b><hr>
link_to(name, options = {}, html_options = nil,  
*parameters_for_method_reference)<br>
<hr>
Creates a link tag of the given <tt>name</tt> using an URL created
by
the set of <tt>options</tt>. See the valid options in link:classes/ 
ActionController/Base.html#M000021. It''s also possible to pass a  
string instead of an options hash to get a link tag that just points  
without consideration. If nil is passed as a name, the link itself  
will become the name. The html_options have a special feature for  
creating javascript confirm alerts where if you pass :confirm =&gt;  
''Are you sure?'', the link will be guarded with a JS popup
asking that
question. If the user accepts, the link is processed, otherwise not.<p>
Example:<p>
<pre>  link_to "Delete this page", { :action =>
"destroy", :id =>
@page.id }, :confirm => "Are you sure?"
</pre>

   <br /><br />
   <b>Snippets, Clarifications and Comments:</b>
   <hr>
=end code snippet ================
Apart from the bad HTML code syntax in the above snippet, it is in my  
mind analogous to implementing this DB.table structure

CREATE TABLE products (
     data text not null
);

where the products information would be stored inside the "data"  
column something like this:
"id|title|description|price|available|etc..|etc.."

Surely no one would argue for that type of DB structure ?

This should in no way be viewed as me complaining about Duane''s work  
or anything like it. I am just trying to help improve something  
before it''s too late, and if I wasn''t a newbie and had my own
projects to begin learning with I''d rework things from the source code.


OK, enough said, and apologies for the length. Ended up longer than  
intended.

Kind regards,

Mats

----
"TextMate, coding with an incredible sense of joy and ease"
- www.macromates.com -

It would be worth checking out the PHP Manual''s about section.
http://www.php.net/manual/en/about.php

On 7/19/05, Mats Persson <mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org>
wrote:
> Using the Raildock site to search for "link_to" [ http://
> raildock.mytechsupport.com/ri/
> ActionView::Helpers::UrlHelper@link_to ] returns a page that is
> containing information, but it''s not easily digestible by either
> humans or regexp.
Mats, you''ve mentioned regexp parsing of the online PHP manual before
as well and I thought I should point out that it isn''t suited to that
nor needs to be because you should get the original source, the XML
DocBook format that the HTML is generated from. It is made to be
parsable.
http://www.php.net/manual/en/about.generate.php

I believe it would be wise for RoR to adopt a baseline format as well
so the documentation can be translated and generated in multiple
formats more easily.

-- 
Chris Griego

I would help with this aswell. Being fairly new I know what I have
been searching for, and an easy to browse php.net like doc is exactly
what is needed IMHO. It would save beginners countless fumbling for
methods and examples. And Im sorry I really dont think wikifying
documentation is helpful at all.

Sam

On 7/19/05, Chris Griego <cgriego-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> It would be worth checking out the PHP Manual''s about section.
> http://www.php.net/manual/en/about.php
> 
> On 7/19/05, Mats Persson
<mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org> wrote:
> > Using the Raildock site to search for "link_to" [ http://
> > raildock.mytechsupport.com/ri/
> > ActionView::Helpers::UrlHelper@link_to ] returns a page that is
> > containing information, but it''s not easily digestible by
either
> > humans or regexp.
> 
> Mats, you''ve mentioned regexp parsing of the online PHP manual
before
> as well and I thought I should point out that it isn''t suited to
that
> nor needs to be because you should get the original source, the XML
> DocBook format that the HTML is generated from. It is made to be
> parsable.
> http://www.php.net/manual/en/about.generate.php
> 
> I believe it would be wise for RoR to adopt a baseline format as well
> so the documentation can be translated and generated in multiple
> formats more easily.
> 
> --
> Chris Griego
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
>

For those interested, I''ll be posting my progress at my blog
www.warpspire.com.  Hopefully within the next few days I can put
together a few prototypes of what _I_ think the documentation should
be like. I''d be interested in hearing input from everyone else on how
certain things should be organized, etc.

On 7/19/05, Sam Mayes <codeslave-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>
wrote:
> I would help with this aswell. Being fairly new I know what I have
> been searching for, and an easy to browse php.net like doc is exactly
> what is needed IMHO. It would save beginners countless fumbling for
> methods and examples. And Im sorry I really dont think wikifying
> documentation is helpful at all.
> 
> Sam
> 
> On 7/19/05, Chris Griego
<cgriego-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> > It would be worth checking out the PHP Manual''s about
section.
> > http://www.php.net/manual/en/about.php
> >
> > On 7/19/05, Mats Persson
<mats-uGq4Pdis5ybkYMGBc/C6ZA@public.gmane.org> wrote:
> > > Using the Raildock site to search for "link_to" [
http://
> > > raildock.mytechsupport.com/ri/
> > > ActionView::Helpers::UrlHelper@link_to ] returns a page that is
> > > containing information, but it''s not easily digestible
by either
> > > humans or regexp.
> >
> > Mats, you''ve mentioned regexp parsing of the online PHP
manual before
> > as well and I thought I should point out that it isn''t suited
to that
> > nor needs to be because you should get the original source, the XML
> > DocBook format that the HTML is generated from. It is made to be
> > parsable.
> > http://www.php.net/manual/en/about.generate.php
> >
> > I believe it would be wise for RoR to adopt a baseline format as well
> > so the documentation can be translated and generated in multiple
> > formats more easily.
> >
> > --
> > Chris Griego
> > _______________________________________________
> > Rails mailing list
> > Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> > http://lists.rubyonrails.org/mailman/listinfo/rails
> >
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
> 

-- 
Kyle Neath
kneath-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
http://www.neathdesign.com

On Tuesday 19 July 2005 21:22, Kyle Neath wrote:
> For those interested, I''ll be posting my progress at my blog
> www.warpspire.com.  Hopefully within the next few days I can put
> together a few prototypes of what _I_ think the documentation should
> be like. I''d be interested in hearing input from everyone else on
how
> certain things should be organized, etc.
Would you mind doing it on the Rails Wiki? I seem to remember there have 
already been complaints about Rails documentation being scattered. 
Distributing potentially valuable information over an ever growing 
number of sites and blogs surely is not going to improve the state.

Information is only useful if it can be found. A good way to achieve 
this aim is to centralize it in one place. For Rails such a place 
already exists: rubyonrails.org and its subdomains.

Michael

-- 
Michael Schuerig                      They tell you that the darkness
mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org                  Is a
blessing in disguise
http://www.schuerig.de/michael/           --Janis Ian, From Me To You

Michael, no offense - I''ve tried the wiki. It''s a mess of lost
jungleness. There is a help-improve-the-docs page, but those
participating made it quite clear RDoc was as far as they were willing
to go.  Plus, I''ll be experimenting in ways the wiki can''t
handle.
Quite honestly, the wiki is what got us to this point - it''s just like
throwing the docs into a giant spiderweb and seeing what sticks where.
There''s no clear navigation or structure, like there should be.

I''d rather wait a while, work on it and show what I have. 
We''re
looking at documentation here, not just an api.

On 7/19/05, Michael Schuerig
<michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org>
wrote:
> On Tuesday 19 July 2005 21:22, Kyle Neath wrote:
> > For those interested, I''ll be posting my progress at my blog
> > www.warpspire.com.  Hopefully within the next few days I can put
> > together a few prototypes of what _I_ think the documentation should
> > be like. I''d be interested in hearing input from everyone
else on how
> > certain things should be organized, etc.
> 
> Would you mind doing it on the Rails Wiki? I seem to remember there have
> already been complaints about Rails documentation being scattered.
> Distributing potentially valuable information over an ever growing
> number of sites and blogs surely is not going to improve the state.
> 
> Information is only useful if it can be found. A good way to achieve
> this aim is to centralize it in one place. For Rails such a place
> already exists: rubyonrails.org and its subdomains.
> 
> Michael
> 
> --
> Michael Schuerig                      They tell you that the darkness
> mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org                  Is
a blessing in disguise
> http://www.schuerig.de/michael/           --Janis Ian, From Me To You
> _______________________________________________
> Rails mailing list
> Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
> http://lists.rubyonrails.org/mailman/listinfo/rails
> 

-- 
Kyle Neath
kneath-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org
http://www.neathdesign.com

On Wednesday 20 July 2005 01:46, Kyle Neath wrote:
> Michael, no offense - I''ve tried the wiki. It''s a mess of
lost
> jungleness. There is a help-improve-the-docs page, but those
> participating made it quite clear RDoc was as far as they were
> willing to go.  Plus, I''ll be experimenting in ways the wiki
can''t
> handle. Quite honestly, the wiki is what got us to this point -
it''s
> just like throwing the docs into a giant spiderweb and seeing what
> sticks where. There''s no clear navigation or structure, like there
> should be.
I''m curious, what kind of structure do you need for docs that the wiki 
can''t handle? I agree completely that a wiki by itself imposes very 
little structure, but it doesn''t prohibit defining a convention for 
more structure on top of it either. With Rails we''ve all seen already 
how powerful convention can be as a tool.

I certainly don''t want to talk you or anyone out of experimenting with 
new ideas for the presentation of documentation. Far from it. But 
that''s a different endeavor from producing documentational content. 
Content can live quite well and usefully on something as inert as 
paper. Devising structures and techniques for presentation is 
undoubtedly a sweet task for a developer, especially when compared to 
writing documentation. From my limited point of view the need for the 
latter is more pressing.

Michael

-- 
Michael Schuerig                  I am the sum total of the parts
mailto:michael-q5aiKMLteq4b1SvskN2V4Q@public.gmane.org        I control
directly.
http://www.schuerig.de/michael/   --Daniel C. Dennett, Elbow Room

Undoubtedly, Michael. Don''t think I''m forgetting this task as
well :)

Here''s my plan though, and keep in mind the only reason I''m
taking
this so "personally" is that  I figure if someone spearheads this and
get something rolling, we''re more likely to come out with something to
show rather than just talking.

1. Build a couple of design prototypes for method pages, class pages, etc
2. IA the whole thing on a very high level. Organize methods and such
into some sort of logical heirarchical structure.
3. Build an app to manage the documentation that makes it easy to
contribute content.
4. Fill it.

Of course, it''s not like I''m going to have a fully functioning
doc
tomorrow. Just something I''ll work on in my spare time, because I feel
I have something to contribute.  The thing is: you need something to
put the writing you have before you can put the writing down.

On Jul 19, 2005, at 2:50 AM, Mats Persson wrote:
>> 2. Example calls of the method (very rare examples in the doc)
>
> Yes, to all of the above, but especially point 2.  Each method with  
> multiple options/params should be shown using all those and what it  
> will return as a result.
Mats, I agree with you on this point.  By your needs analysis, does  
RailDock''s per-method ''snippets'' cover this feature? 
My intent for
the snippets attached to each method (like PHP''s comments) was to  
allow user suggestions and practical code samples for each method.
>> I''d love to help in this push if others are interested. 
However
>> some serious planning is in order. I don''t think this is a
build-
>> it-and-think-later thing. This involves some serious IA and  
>> thought about the best way to display and organize the methods/ 
>> classes
>> found in rails.
>>
This is a good point.  With regard to RailDock, I''ve thought of the  
project so far as more of a "prototype push" than a full-featured or  
well-thought-out site.  While it at least provides *something* out  
there, I am not entirely satisfied with its search capability (nor  
its middle-tier documentation at this point).
> The current implementation of Raildock [ http:// 
> raildock.mytechsupport.com/ ]  (I''m using Raildock as an example,
> since it''s current and the only one i know about) is a start, but
> it is also flawed in GUI terms, and I''m afraid of it being a dead
> end road full of wasted time and energy unless it''s corrected
asap.
> OK, possibly strong words, but here''s the argument for that point
> of view.
I''m glad it''s at least given us a reference point :)
> Using the Raildock site to search for "link_to" [ http:// 
> raildock.mytechsupport.com/ri/ 
> ActionView::Helpers::UrlHelper@link_to ] returns a page that is  
> containing information, but it''s not easily digestible by either  
> humans or regexp.
>
> -- It is visually difficult to read the information on that page,  
> due to text colour, white space and information structuring issues.  
> In other words it seems more like a republishing of available  
> documentation rather than an attempt to re-invent a badly  
> structured documentation.
>
Can you provide a mock-up of what you''d like to see?  Layout-wise, it  
would be very easy to update.
> -- The UI is functional, but the PHP manual beats it hands down.  
> Select menus may save space, but reduces overview and context  
> comprehension.
>
What do other people think about this?  Any suggestions?
> --  When looking at the relevant HTML code output this is how it  
> looks like:
>
> =begin code snippet ================> <snip>
> =end code snippet ================>
> Apart from the bad HTML code syntax in the above snippet, it is in  
> my mind analogous to implementing this DB.table structure
>
> CREATE TABLE products (
>     data text not null
> );
>
> where the products information would be stored inside the "data"
> column something like this:
> "id|title|description|price|available|etc..|etc.."
>
> Surely no one would argue for that type of DB structure ?
>
This is a good point.  The strength of RailDock at this point is its  
ease-of-conversion from the (live) rdoc source to a searchable  
structure presented in HTML.  However, it isn''t implemented quite as  
simplistically as you''ve indicated.  The RI (ruby info) format does  
separate informational segments in to logical sections--for example,  
title, summary, class methods, and instance methods are all sections  
that we could easily separate out and format differently.  What  
you''re seeing, in any case, is just my use of the default  
RI::HtmlFormatter with some tweaks of my own to get links working on  
RailDock.  There is currently no database in use by RailDock, other  
than for the snippets.

As has been discussed before on the wiki [http://wiki.rubyonrails.com/ 
rails/show/RorDocGoals] there is a definite need to leverage the in- 
source documentation (which often changes on a per-release basis) for  
a public documentation site.  As Xal suggested, ideally we should be  
able to edit the documentation and re-insert it back in to the source  
code.  If we don''t *at least* use the in-source docs to create public  
docs, then it''s going to be a sad state of incongruency between the  
public documentation and the in-source documentation.
> This should in no way be viewed as me complaining about Duane''s  
> work or anything like it. I am just trying to help improve  
> something before it''s too late, and if I wasn''t a newbie
and had my
> own projects to begin learning with I''d rework things from the  
> source code.
>
Before it''s tooooo laaaate!  :)

Thanks for your constructive criticism, Mats.  Let''s keep working on  
this.

Duane Johnson
(canadaduane)




_______________________________________________
Rails mailing list
Rails-1W37MKcQCpIf0INCOvqR/iCwEArCW2h5@public.gmane.org
http://lists.rubyonrails.org/mailman/listinfo/rails

One of the advantages of php.net-type documentation over the wiki --
is constraint. A core doc team determine how the "book" should be laid
out, chapters, sections, etc -- and only the core team work on the
documentation part. If there is an error or things that can be added
-- it can submitted like a patch to the team.

User comments are powerful, too. Mysql has a similar system and it''s
helped me out in pinches many times. Wiki comments are totally
inconsistent. PHP.net/Mysql comments are usually in this format: users
finding solutions to their problems and posting them.

Kyle -- good luck on leading this project. I don''t know how much
you''re going to be focusing on design of the webpage versus design of
the "book" -- but I''d heartily love to see a thread started
that looks
at the "book" design part. A wiki page inside rubyonrails.com could be
lit up to create the outline and a thread could be used here to
discuss.

Ben