In my opionion, the rdocs are really dificult to read right now. I think if I
was picking up watir now and looking at the rdocs for the first time, Id be a
bit disheartened.
I would make sure that only relevant ( to the end user )
methods/classes/modules are in the rdoc
you can switch off rdoc like this
#--
# I dont get documented
def foo
end
#++
there are lots of methods that really dont help the user as far as documenting
them, eg element_tag ( Watir::xxx ) and the methods that people would care
about ( click , set etc ) are kind of hidden.
Id maybe also try to minimize the usage of the method descrioptions by making a
really good intro section ( see the rails docs, especially ActiveRecord::Base
( http://api.rubyonrails.org/classes/ActiveRecord/Base.html )
If you do a good intro maybe broken into
1- what watir is, ( license etc )
2 - finding objects using irb
- using show_xx abd xx.show methods, flash, to_s
3 - finding objects using :index, :value :class etc
4 - methods particular to several objects ( with links to the full list of
methods ) like
ie.link(:id, 'x').click
ie.button(:name , 'y').value
5 - then get into the rdocs like the rails docs do
Hope that helps
Paul
----- Original Message -----
From: Jeff Fry
To: wtr-general@rubyforge.org
Sent: Tuesday, May 08, 2007 8:06 PM
Subject: [Wtr-general] RDOC - Help determining what needs documentation
OK, I've learned (and documented on the wiki) how to: create a svn working
copy, edit the rdoc text, generate an rdoc using rake, and then generate a
patch file. There is of course a crucial step missing there...and that's
knowing what needs to be documented.
Brett and I had hoped that a way to find some of what needs documenting was
for me to read through his tagged Thunderbird archive of watir posts. After
some wrangling, I got the mail...but not the tags. >From this conversation on
the Thunderbird forums, it seems like the tags can't be transfered:
I'm left hoping we can find another way for me to learn what's been added but
not documented in v1.5. So Brett, Charley, Paul, or others involved in building
v1.5...if you were going to update the rdoc, how would you know what to edit?
If you were going to be making the edits yourself, what parts are most time
consuming for you? Would it be worth your time come up with a rough list of
things that need documentation and pass that to someone else to document? Or
does generating that list constitute the bulk of the work, after which there's
not much point in delegating the writing? Alternately, is there a way that you
could teach me to generate that list of things that needs documenting?
One specific example - how can I determine what methods can take :class as a
parameter? I know that this works for button, text_field and div...but is there
a way I can find out what other methods take :class via searching source code
in eclipse? I just tried reading & searching watir.rb for clues...but I got
lost.
I hope I can find a way through this last crucial step so that I can submit a
useful rdoc patch. If I manage to get or generate a list of to-dos, I can still
easily put a full day into editing the rdoc...but I'll need to do that day
between now and early this Friday. After that I'm away for a weekend and then
starting a new job, where I suspect I'll be too overwhelmed for a month or two
to contribute significantly.
Thanks,
Jeff
--
http://testingjeff.wordpress.com
------------------------------------------------------------------------------
_______________________________________________
Wtr-general mailing list
Wtr-general@rubyforge.org
http://rubyforge.org/mailman/listinfo/wtr-general_______________________________________________
Wtr-general mailing list
Wtr-general@rubyforge.org
http://rubyforge.org/mailman/listinfo/wtr-general
