Hey, I want to open some discussion here, as I didn't notice this until now: http://github.com/shoes/shoes/issues#issue/58 Two things: #1, the github wikis are already git-backed. http://github.com/blog/699-making-github-more-open-git-backed-wikis "Just add ".wiki" to any repository name in the URL, and you're ready to go." Second... we already have a wiki manual, on github. I'm not really sure why we'd need to wiki-ify the manual itself. If someone wants to make changes... they can do so with a pull request. (in before jokes about how i'm bad at responding to pull requests) Third... I think this broaches a broader topic: the shoes documentation could probably used beefed up a bit, in places. We've had people stop by the IRC lately and ask about RDOC, for example. Thoughts, anyone? I think the manual is pretty awesome, but there are certainly some rough spots...
> > Hey, I want to open some discussion here, as I didn't notice this until > now: > > http://github.com/shoes/shoes/issues#issue/58 > > Thanks for posting this here Steve, I think this is definitely an area of interest for shoes newbies and oldtimers alike > Two things: #1, the github wikis are already git-backed. > http://github.com/blog/699-making-github-more-open-git-backed-wikis > > "Just add ".wiki" to any repository name in the URL, and you're ready to > go." > > I didn't know that, awesome! A mention of this as apart of a "contributing to shoes" section would be beneficial. > Second... we already have a wiki manual, on github. I'm not really > sure why we'd need to wiki-ify the manual itself. If someone wants to > make changes... they can do so with a pull request. (in before jokes > about how i'm bad at responding to pull requests) > > The manual might be easier to maintain and contribute to if it was in a separate repository. Then you can have someone who, they're job is to just manage the book and pull requests. Without even touching the shoes master. > Third... I think this broaches a broader topic: the shoes > documentation could probably used beefed up a bit, in places. We've > had people stop by the IRC lately and ask about RDOC, for example. > Thoughts, anyone? I think the manual is pretty awesome, but there are > certainly some rough spots... > Without starting a yard vs. rdoc war, I'd like to say that either way it's got to be done at some point. It may not be entirely possible with the current shoes implementation, but down the road we'll definitely have to address this concern. The manual covers the API pretty closely, and it drives the line of tutorial and API documentation pretty well. There's just no replacing a rdoc.info API resource however.. But since the current shoes implementation will never be very rdoc friendly, perhaps we should make it a todo for some indepth shoes source commenting. Since all of that is readily available on github, and there are some excellent articles in the wiki to go along with it, thanks to Cecil. -- Zachary Scott http://zacharyscott.net/ http://twitter.com/hasmanytweets
I have to have to top quote, instead of point by point reply. In my annoying way, I'll bring up a couple of related points worth thinking about. 1. Is anybody busting a gut writing new sections of the builtin Shoes manual? Fix a typo, for sure or add a sentence or two but the _why manual kind of . IMO, not a problem to solve. 2. If someone can figure out how to make the Shoes built in manual a separate project that is used by all the multicolored shoes that would be great. Sadly, it's kind of like the packager. One depends on the other. It's not Shoes without them and they both need Shoes to execute. Before you hand wave "it's going to be packaged as a 'shoesdoc gem', just like the mythical 'packager' gem of the future", think about how that will actually work - draw it out on napkin with blocks and arrows. One napkin diagram for what the user sees and does on Windows/OSX/Linux and another napkin for what the developer sees. 3. Rdoc like documentation would be fabulous for people with thinking patterns. The Shoes manual is lovely but it doesn't tell me what methods and those args are available for para without a click to some place that doesn't have a back button if I guessed wrong. It might be possible to setup Rdoc comments in Red Shoes C files. But if you did, that won't help the Blue/Green/Brown/.... They have to duplicate the doc/comments in their code base. I can think of complex ways to fix that, way's that won't work in the real world. When separate manual and packager, then you might as well separate the rdoc subproject. On the good news front, the White Shoes folks have some new specs to write tests for -- the manual. I'm sure they are running low of things to do. 4, Shoes has splintered apart! Possibly forever. Some info at heroku, some at github forks of forks, some at the mailing list, some info (not much, but fun) at IRC, and on any webpage that allows comments or editing. Running in a thousand directions at once is not the way to move a project forward. With all due respect to the thousand cats working on the multicolored Shoes. Yes, I am cranky tonight because I've got a Ubuntu PulseAudio problem without a solution. Not a new problem either, quite well known. It's a lesson for Shoes developers. Ubuntu invented Pulseaudio to fix all the sound problems. They created a new abstract layer (and code and server daemons) to hide all the nasty bugs below. Abstract their troubles away. Except you can't fix things by wishing them away. On Thu, 2010-10-28 at 12:11 -0400, Zachary Scott wrote: > Hey, I want to open some discussion here, as I didn't notice > this until now: > > http://github.com/shoes/shoes/issues#issue/58 > > > > Thanks for posting this here Steve, I think this is definitely an area > of interest for shoes newbies and oldtimers alike > > Two things: #1, the github wikis are already git-backed. > http://github.com/blog/699-making-github-more-open-git-backed-wikis > > "Just add ".wiki" to any repository name in the URL, and > you're ready to go." > > > > I didn't know that, awesome! A mention of this as apart of a > "contributing to shoes" section would be beneficial. > > Second... we already have a wiki manual, on github. I'm not > really > sure why we'd need to wiki-ify the manual itself. If someone > wants to > make changes... they can do so with a pull request. (in before > jokes > about how i'm bad at responding to pull requests) > > > > The manual might be easier to maintain and contribute to if it was in > a separate repository. Then you can have someone who, they're job is > to just manage the book and pull requests. Without even touching the > shoes master. > > Third... I think this broaches a broader topic: the shoes > documentation could probably used beefed up a bit, in places. > We've > had people stop by the IRC lately and ask about RDOC, for > example. > Thoughts, anyone? I think the manual is pretty awesome, but > there are > certainly some rough spots... > > > Without starting a yard vs. rdoc war, I'd like to say that either way > it's got to be done at some point. It may not be entirely possible > with the current shoes implementation, but down the road we'll > definitely have to address this concern. The manual covers the API > pretty closely, and it drives the line of tutorial and API > documentation pretty well. There's just no replacing a rdoc.info API > resource however.. Rdoc is good for experienced Ruby folks. You can't really generate it from C source code (Red Shoes) like you might with Ruby source code. Or maybe we can? Can we mark up C code for rdoc processing. > > > But since the current shoes implementation will never be very rdoc > friendly, perhaps we should make it a todo for some indepth shoes > source commenting. Since all of that is readily available on github, > and there are some excellent articles in the wiki to go along with it, > thanks to Cecil. > > > -- > Zachary Scott > > http://zacharyscott.net/ > http://twitter.com/hasmanytweets
On Thu, Oct 28, 2010 at 10:58 PM, Cecil Coupe <ccoupe@cableone.net> wrote: > I have to have to top quote, instead of point by point reply. In my > annoying way, I'll bring up a couple of related points worth thinking > about. > > 1. Is anybody busting a gut writing new sections of the builtin Shoes > manual? Fix a typo, for sure or add a sentence or two but the _why > manual kind of . IMO, not a problem to solve. > > 2. If someone can figure out how to make the Shoes built in manual a > separate project that is used by all the multicolored shoes that would > be great. Sadly, it's kind of like the packager. One depends on the > other. It's not Shoes without them and they both need Shoes to execute. > > Before you hand wave "it's going to be packaged as a 'shoesdoc gem', > just like the mythical 'packager' gem of the future", think about how > that will actually work - draw it out on napkin with blocks and arrows. > > One napkin diagram for what the user sees and does on Windows/OSX/Linux > and another napkin for what the developer sees. > I see what you're getting at. It's the same point as before. We would probably be doing the DataMapper/Merb-like approach. A virtual “xxxxx-shoes” gem for each color, which depend on, for example, “shoes-manual” and “shoes-packager” and “xxxxx-shoes-core” or something like that. But the average user wouldn't even have to worry about that! Installer packages would take care of setting up a self-contained environment like any other application *for* them. The nice thing about this is that the gems would be installable by more seasoned developers who want to tweak their environment and perhaps only grab certain components of Shoes. It gives more options, while not inconveniencing the user. Trust me, we will have Shoes app gem dependency working for this. And it will be easy. I feel like I'm having to explain the same thing over and over again. > > 3. Rdoc like documentation would be fabulous for people with thinking > patterns. The Shoes manual is lovely but it doesn't tell me what methods > and those args are available for para without a click to some place that > doesn't have a back button if I guessed wrong. > > It might be possible to setup Rdoc comments in Red Shoes C files. But if > you did, that won't help the Blue/Green/Brown/.... They have to > duplicate the doc/comments in their code base. I can think of complex > ways to fix that, way's that won't work in the real world. When separate > manual and packager, then you might as well separate the rdoc > subproject. > > On the good news front, the White Shoes folks have some new specs to > write tests for -- the manual. I'm sure they are running low of things > to do. > > 4, Shoes has splintered apart! Possibly forever. Some info at heroku, > some at github forks of forks, some at the mailing list, some info (not > much, but fun) at IRC, and on any webpage that allows comments or > editing. Running in a thousand directions at once is not the way to move > a project forward. > > With all due respect to the thousand cats working on the multicolored > Shoes. > > Yes, I am cranky tonight because I've got a Ubuntu PulseAudio problem > without a solution. Not a new problem either, quite well known. It's a > lesson for Shoes developers. Ubuntu invented Pulseaudio to fix all the > sound problems. They created a new abstract layer (and code and server > daemons) to hide all the nasty bugs below. Abstract their troubles away. > Except you can't fix things by wishing them away. > > > On Thu, 2010-10-28 at 12:11 -0400, Zachary Scott wrote: > > Hey, I want to open some discussion here, as I didn't notice > > this until now: > > > > http://github.com/shoes/shoes/issues#issue/58 > > > > > > > > Thanks for posting this here Steve, I think this is definitely an area > > of interest for shoes newbies and oldtimers alike > > > > Two things: #1, the github wikis are already git-backed. > > > http://github.com/blog/699-making-github-more-open-git-backed-wikis > > > > "Just add ".wiki" to any repository name in the URL, and > > you're ready to go." > > > > > > > > I didn't know that, awesome! A mention of this as apart of a > > "contributing to shoes" section would be beneficial. > > > > Second... we already have a wiki manual, on github. I'm not > > really > > sure why we'd need to wiki-ify the manual itself. If someone > > wants to > > make changes... they can do so with a pull request. (in before > > jokes > > about how i'm bad at responding to pull requests) > > > > > > > > The manual might be easier to maintain and contribute to if it was in > > a separate repository. Then you can have someone who, they're job is > > to just manage the book and pull requests. Without even touching the > > shoes master. > > > > Third... I think this broaches a broader topic: the shoes > > documentation could probably used beefed up a bit, in places. > > We've > > had people stop by the IRC lately and ask about RDOC, for > > example. > > Thoughts, anyone? I think the manual is pretty awesome, but > > there are > > certainly some rough spots... > > > > > > Without starting a yard vs. rdoc war, I'd like to say that either way > > it's got to be done at some point. It may not be entirely possible > > with the current shoes implementation, but down the road we'll > > definitely have to address this concern. The manual covers the API > > pretty closely, and it drives the line of tutorial and API > > documentation pretty well. There's just no replacing a rdoc.info API > > resource however.. > > Rdoc is good for experienced Ruby folks. You can't really generate it > from C source code (Red Shoes) like you might with Ruby source code. Or > maybe we can? Can we mark up C code for rdoc processing. > You can, actually. Ruby's core documentation is like this. > > > > > > > But since the current shoes implementation will never be very rdoc > > friendly, perhaps we should make it a todo for some indepth shoes > > source commenting. Since all of that is readily available on github, > > and there are some excellent articles in the wiki to go along with it, > > thanks to Cecil. > > > > > > -- > > Zachary Scott > > > > http://zacharyscott.net/ > > http://twitter.com/hasmanytweets > > > -- ~devyn