Eventmachine talk - Jan 2008 - EM docs: FAQ and HOWTO rdoc files

Hi Devs,
I like the ''extra'' RDoc files included in the EM gem, e.g.
SMTP,
DEFFERRABLES, etc.

IMO it''d be nice to add FAQ and HOWTO files.

One issue is there are likely to be different levels of users interested:
 - Technically sophisticated devs (not me)
 - Intermediate users who know what they need to do (more like me),
just not fully sure howto get it done ''best''.
 - Beginners.

Is it worth structuring rdocs with this in mind or leave this to wiki type docs?
While the documentation infrastructure is different I always _really_
liked the organization of TAO''s manual pages:
http://www-unix.mcs.anl.gov/tao/docs/manualpages/solver/index.html

I think it saved me countless hours by steering me to the
''material''
most appropriate to me.

I think somthing similar might be possible with rdocs?

HTH?
Mark

On Jan 3, 2008 7:45 PM, Mark Van De Vyver <mvyver at gmail.com> wrote:
> Hi Devs,
> I like the ''extra'' RDoc files included in the EM gem,
e.g. SMTP,
> DEFFERRABLES, etc.
>
> IMO it''d be nice to add FAQ and HOWTO files.
>
> One issue is there are likely to be different levels of users interested:
>  - Technically sophisticated devs (not me)
>  - Intermediate users who know what they need to do (more like me),
> just not fully sure howto get it done ''best''.
>  - Beginners.
>
> Is it worth structuring rdocs with this in mind or leave this to wiki type
> docs?
> While the documentation infrastructure is different I always _really_
> liked the organization of TAO''s manual pages:
> http://www-unix.mcs.anl.gov/tao/docs/manualpages/solver/index.html
>
> I think it saved me countless hours by steering me to the
''material''
> most appropriate to me.
>
> I think somthing similar might be possible with rdocs?
>

My sense is that EM has gotten too big for a single FAQ and a single HOWTOs
file. Your suggestion from TAO seems to be about categorizing the API
reference, which isn''t a bad idea. Also have a look at
Twisted''s online
docs. They have big lists of Howtos categorized in multiple ways. Something
like that would be nice for us.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
http://rubyforge.org/pipermail/eventmachine-talk/attachments/20080103/73e7754c/attachment.html

On Jan 4, 2008 12:13 PM, Francis Cianfrocca <garbagecat10 at gmail.com>
wrote:
>
> On Jan 3, 2008 7:45 PM, Mark Van De Vyver <mvyver at gmail.com>
wrote:
>
>
> > Hi Devs,
> > I like the ''extra'' RDoc files included in the EM
gem, e.g. SMTP,
> > DEFFERRABLES, etc.
> >
> > IMO it''d be nice to add FAQ and HOWTO files.
> >
> > One issue is there are likely to be different levels of users
interested:
> >  - Technically sophisticated devs (not me)
> >  - Intermediate users who know what they need to do (more like me),
> > just not fully sure howto get it done ''best''.
> >  - Beginners.
> >
> > Is it worth structuring rdocs with this in mind or leave this to wiki
type
> docs?
> > While the documentation infrastructure is different I always _really_
> > liked the organization of TAO''s manual pages:
> > http://www-unix.mcs.anl.gov/tao/docs/manualpages/solver/index.html
> >
> > I think it saved me countless hours by steering me to the
''material''
> > most appropriate to me.
> >
> > I think somthing similar might be possible with rdocs?
> >
>
> My sense is that EM has gotten too big for a single FAQ and a single HOWTOs
OK.
But does this mean you think these files should be distributed with
the gem as per SMTP, etc.?
Or should they be separated/isolated from the gem?
> file. Your suggestion from TAO seems to be about categorizing the API
> reference, which isn''t a bad idea.
Hopefully it can be done?
> Also have a look at Twisted''s online
> docs. They have big lists of Howtos categorized in multiple ways. Something
> like that would be nice for us.
Twisted''s (who thought a nest of snakes as a book image was a good
idea?!) FAQ, examples and howtos are a good starting point, hopefully
we could improve or some aspects.

Their FAQ gives us a some hints at the starting questions - clearly
not all are relevant to EM.

The examples and howtos could also reside in the gem?
Or be seperated?

Do we want to adopt Twisted ''categories'' style which seem to
be
library/module orientated, or should we try for more task/activity
orientated.
E.g. would the examples and howtos be:
 - Deferrable (would focus on EM::Deferrable*)
 - Stomp, etc. (would focus on EM::Protocols::Stomp)

Or would they be along the lines of:
 - Blocking (would not necessarily limit focus to EM::Deferrable*)
 - Messaging (would not necessarily limit focus to EM::Protocols::Stomp)

Cheers
Mark

Just for the record, How-to-create-a-custom-RDoc-generator:

http://snippets.aktagon.com/snippets/82-How-to-create-a-custom-RDoc-generator

On Jan 4, 2008 2:35 PM, Mark Van De Vyver <mvyver at gmail.com>
wrote:
> On Jan 4, 2008 12:13 PM, Francis Cianfrocca <garbagecat10 at
gmail.com> wrote:
> >
> > On Jan 3, 2008 7:45 PM, Mark Van De Vyver <mvyver at gmail.com>
wrote:
> >
> >
> > > Hi Devs,
> > > I like the ''extra'' RDoc files included in the
EM gem, e.g. SMTP,
> > > DEFFERRABLES, etc.
> > >
> > > IMO it''d be nice to add FAQ and HOWTO files.
> > >
> > > One issue is there are likely to be different levels of users
interested:
> > >  - Technically sophisticated devs (not me)
> > >  - Intermediate users who know what they need to do (more like
me),
> > > just not fully sure howto get it done ''best''.
> > >  - Beginners.
> > >
> > > Is it worth structuring rdocs with this in mind or leave this to
wiki type
> > docs?
> > > While the documentation infrastructure is different I always
_really_
> > > liked the organization of TAO''s manual pages:
> > >
http://www-unix.mcs.anl.gov/tao/docs/manualpages/solver/index.html
> > >
> > > I think it saved me countless hours by steering me to the
''material''
> > > most appropriate to me.
> > >
> > > I think somthing similar might be possible with rdocs?
> > >
> >
> > My sense is that EM has gotten too big for a single FAQ and a single
HOWTOs
>
> OK.
> But does this mean you think these files should be distributed with
> the gem as per SMTP, etc.?
> Or should they be separated/isolated from the gem?
>
> > file. Your suggestion from TAO seems to be about categorizing the API
> > reference, which isn''t a bad idea.
>
> Hopefully it can be done?
>
> > Also have a look at Twisted''s online
> > docs. They have big lists of Howtos categorized in multiple ways.
Something
> > like that would be nice for us.
>
> Twisted''s (who thought a nest of snakes as a book image was a good
> idea?!) FAQ, examples and howtos are a good starting point, hopefully
> we could improve or some aspects.
>
> Their FAQ gives us a some hints at the starting questions - clearly
> not all are relevant to EM.
>
> The examples and howtos could also reside in the gem?
> Or be seperated?
>
> Do we want to adopt Twisted ''categories'' style which seem
to be
> library/module orientated, or should we try for more task/activity
> orientated.
> E.g. would the examples and howtos be:
>  - Deferrable (would focus on EM::Deferrable*)
>  - Stomp, etc. (would focus on EM::Protocols::Stomp)
>
> Or would they be along the lines of:
>  - Blocking (would not necessarily limit focus to EM::Deferrable*)
>  - Messaging (would not necessarily limit focus to EM::Protocols::Stomp)
>
> Cheers
> Mark
>