Hey everybody- I'm working on the documentation for Red Shoes, and I was wondering what you guys would like to see. What's good about our current docs? What's bad?
There is an interesting thing about the docs that really shows _why was using a different lobe of the brain than me, the artistic side. Nobody knows Shoes was more obviously 'arty' than rdoc. It would be a shame to lose that. What annoys me is the lack of a back button. Perhaps I'm refreshing my memory on Elements:Button and there is a link to common styles. Click that and you can't easily find your way back to the Button doc you left. Same with the search. It's not the documentation but the navigation that needs work. Ick. A tutorial/wiki-post on Shoes::Widgets would be useful as would be another tutorial/article of the module/app scoping rules. Those should be for Rubyists that don't know that Shoes is a different Ruby. On Tue, 2011-06-21 at 11:05 -0400, Steve Klabnik wrote: > Hey everybody- > > I'm working on the documentation for Red Shoes, and I was wondering > what you guys would like to see. What's good about our current docs? > What's bad? >
Steve, I like examples like the ones ashbb has been posting to the mailing list recently. jQuery docs do a nice job with including examples. I would love to contribute here as soon as I can build it (might have to fire up a VM). And documenting all of the methods available would be another nice goal. Eric
hey steve, one of the things i would personally like to know more about is extending shoes, as i only recently found out about widgets and such. so, widgets and anything else that extends shoes - kind of like all the meta-GUI stuff - would be nice to have some docs about. thanks!! hex On Tue, Jun 21, 2011 at 11:05 AM, Steve Klabnik <steve@steveklabnik.com>wrote: > Hey everybody- > > I'm working on the documentation for Red Shoes, and I was wondering what > you guys would like to see. What's good about our current docs? What's bad? > -- > > Other than the fact Linux has a cool name, could someone explain why I > > should use Linux over BSD? > > No. That's it. The cool name, that is. We worked very hard on > creating a name that would appeal to the majority of people, and it > certainly paid off: thousands of people are using linux just to be able > to say "OS/2? Hah. I've got Linux. What a cool name". 386BSD made the > mistake of putting a lot of numbers and weird abbreviations into the > name, and is scaring away a lot of people just because it sounds too > technical. -- Linus Torvalds' follow-up to a question about Linux
hi steve -
three cheers for more shoes docs... your effort is greatly appreciated.
i definitely agree with serialhex that more information about extending
shoes through widgets, and how to make those widgets interact with a main
app would be good. the observer class that you mentioned has worked quite
well for me, as do yield blocks.
i5m's suggestion about more layout information is also a good one...
another thing i would suggest, and would be happy to help out with if i
can, is creating a more complete list of all the methods available to a
given element. the manual covers some but not all of them - when looking
for available methods i usually do something like this:
Shoes.app do
pr = para "hi there"
pr.methods.sort.each{|m| p m}
end
this gives a list of methods, but i often find that i can't figure out how
to use them. 'para' for example shows a 'click' method, and
'pr.respond_to?(:click)' returns true - but if i try a line like
'pr.click{para "clicked"}', it's nothing doing... i search through the
manual (the manual's search box is a great idea!) using 'click,' 'text
block,' and 'para' as keywords, but don't see anything that tells me you can
click on a text block the way you can a link. i realize this point is
somewhat moot because a link element can be styled and used as clickable
text - but why does 'para' show a 'click' method? does it really exist? if
so, how the heck do you use it?
a more complete listing of available methods and an example of their usage
would be extremely helpful...
again, thanks for undertaking this documentation project - i think it
could bring a lot more folks to shoes - and if there's any way that i can
help out just say the word.
- j
Awesome, great suggestions, guys! There is rdoc here, for some of the 'what methods are there' kinds of questions: http://rdoc.info/github/why/shoes That said, it's woefully incomplete. j, if you want to help with this, I can absolutely show you how it's done. Basically, I'm looking to reorganize the entire Shoes site, and documentation should be a big part of it. I'm also looking to integrate the shoebox as well. This is going to be my big project for Whyday, along with a 3.1 release. On Tuesday, June 21, 2011 at 12:59 PM, J. Kaiden wrote: > hi steve - > > three cheers for more shoes docs... your effort is greatly appreciated. > > i definitely agree with serialhex that more information about extending shoes through widgets, and how to make those widgets interact with a main app would be good. the observer class that you mentioned has worked quite well for me, as do yield blocks. > > i5m's suggestion about more layout information is also a good one... > > another thing i would suggest, and would be happy to help out with if i can, is creating a more complete list of all the methods available to a given element. the manual covers some but not all of them - when looking for available methods i usually do something like this: > > Shoes.app do > pr = para "hi there" > pr.methods.sort.each{|m| p m} > end > > this gives a list of methods, but i often find that i can't figure out how to use them. 'para' for example shows a 'click' method, and 'pr.respond_to?(:click)' returns true - but if i try a line like 'pr.click{para "clicked"}', it's nothing doing... i search through the manual (the manual's search box is a great idea!) using 'click,' 'text block,' and 'para' as keywords, but don't see anything that tells me you can click on a text block the way you can a link. i realize this point is somewhat moot because a link element can be styled and used as clickable text - but why does 'para' show a 'click' method? does it really exist? if so, how the heck do you use it? > > a more complete listing of available methods and an example of their usage would be extremely helpful... > > again, thanks for undertaking this documentation project - i think it could bring a lot more folks to shoes - and if there's any way that i can help out just say the word. > > - j
hey Steve, wow, 3.1 - excited to see it... if there's any way i can help i'm more than willing to do so. i'm a hobbyist hack and no kind of programmer, so i'm not sure of how much use i'll be - but i can write, and documenting shoes seems a project that is well worth the effort. i could contribute with any examples of realizations/revelations that i've had about shoes (mostly mooched off of you all!) - and if you'd like to dump some 'raw' info on me i could try to make it readable. i could also fiddle around with all the methods that appear for a given element and try to figure stuff out - but with my thick skull and limited time that might not be of much worth! let me know what i can do, and i'll be happy to help. ...thanks for the rdoc link! - j
Just off the top of my head: there's a lot of useful stuff in Nobody Knows Shoes that isn't in the built-in help docs, especially with regard to how the layout of stacks and flows works. ----------------------- i5m.co.uk GPG Key: 0xA18A602B On Tue, Jun 21, 2011 at 4:05 PM, Steve Klabnik <steve@steveklabnik.com> wrote: > Hey everybody- > > I'm working on the documentation for Red Shoes, and I was wondering what you > guys would like to see. What's good about our current docs? What's bad?