librelist archives

« back to archive

A few thoughts about the manual

A few thoughts about the manual

From:
Steve Klabnik
Date:
2010-10-28 @ 15:24
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...

Re: [shoes] A few thoughts about the manual

From:
Zachary Scott
Date:
2010-10-28 @ 16:11
>
> 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

Re: [shoes] A few thoughts about the manual

From:
Cecil Coupe
Date:
2010-10-29 @ 05:58
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

Re: [shoes] A few thoughts about the manual

From:
Devyn Cairns
Date:
2010-10-30 @ 17:48
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