librelist archives

« back to archive

Documentation: How can we improve?

Documentation: How can we improve?

From:
Steve Klabnik
Date:
2012-01-06 @ 16:41
Threads are useful to focus on one topic!

Wayne has offered to help with documentation. It's also one of my
goals this year, so let's talk about it!

The good:

The manual, overall, is pretty good:
http://shoesrb.com/manual/Hello.html It still has some sore points,
but I use it all the time.

We have some great writing by Cecil here:
https://github.com/shoes/shoes/wiki/A-Developer%27s-Tour-Through-Shoes
and here: 
https://github.com/shoes/shoes/wiki/A-Developer%27s-Tour-Through-The-Magic-Packager

The bad:

The rdoc is basically nonexistant: http://rubydoc.info/github/why/shoes

The biggest stumbling block I've had is understanding how all the
parts fit together. Shoes has lots of little fiddly parts; Cecil's
stuff is a good start, but I'd love to see more things like that. Of
course, this is the hardest to write...

Whatcha think? What's our biggest documentation issue?

Re: [shoes] Documentation: How can we improve?

From:
Wayne Brisette
Date:
2012-01-06 @ 17:13
I'm not sure where I found this, but I have a print out called Shoes Tutorial 
Note that ashbb wrote that is very good. I learned quite a bit about how shoes 
worked going through that document. Ashbb, where can people find that document? 

Wayne


----- Original Message ----
From: Steve Klabnik <steve@steveklabnik.com>
To: shoes@librelist.com
Sent: Fri, January 6, 2012 10:41:08 AM
Subject: [shoes] Documentation: How can we improve?

Threads are useful to focus on one topic!

Wayne has offered to help with documentation. It's also one of my
goals this year, so let's talk about it!

The good:

The manual, overall, is pretty good:
http://shoesrb.com/manual/Hello.html It still has some sore points,
but I use it all the time.

We have some great writing by Cecil here:
https://github.com/shoes/shoes/wiki/A-Developer%27s-Tour-Through-Shoes
and here: 

https://github.com/shoes/shoes/wiki/A-Developer%27s-Tour-Through-The-Magic-Packager


The bad:

The rdoc is basically nonexistant: http://rubydoc.info/github/why/shoes

The biggest stumbling block I've had is understanding how all the
parts fit together. Shoes has lots of little fiddly parts; Cecil's
stuff is a good start, but I'd love to see more things like that. Of
course, this is the hardest to write...

Whatcha think? What's our biggest documentation issue?

Re: [shoes] Documentation: How can we improve?

From:
ashbb
Date:
2012-01-07 @ 00:04
Hi Wayne,

> Wayne has offered to help with documentation.
Awesome! Fantastic!!

> where can people find that document?
Ah,.. are you looking for the url?
Shoes Tutorial Note is on Heroku.

http://shoes-tutorial-note.heroku.com/

Not been updated for over one yeah. :-P

ashbb

Re: [shoes] Documentation: How can we improve?

From:
Peter Fitzgibbons
Date:
2012-01-07 @ 04:47
Fantastic!
Steve, can we get that added to shoesrb.com ?

Peter Fitzgibbons
(847) 859-9550
Email: peter.fitzgibbons@gmail.com
IM GTalk: peter.fitzgibbons
IM AOL: peter.fitzgibbons@gmail.com


On Fri, Jan 6, 2012 at 6:04 PM, ashbb <ashbbb@gmail.com> wrote:

> Hi Wayne,
>
>
> > Wayne has offered to help with documentation.
> Awesome! Fantastic!!
>
>
> > where can people find that document?
> Ah,.. are you looking for the url?
> Shoes Tutorial Note is on Heroku.
>
> http://shoes-tutorial-note.heroku.com/
>
> Not been updated for over one yeah. :-P
>
> ashbb
>