I really don't like having the manual on git. I feel instead we should
have some kind of a database resembling a wikish thing somewhere on
shoooes.net as the primary storage, not necessarily publicly
accessible. From that we would export the static public html manual on
the site, as well as the manual data file which the website could
commit to git automatically when changes are made. We could do this
using http://github.com/judofyr/gash/tree/master
Just having that architecture would give us a lot of freedom with the
manual. If we take projects like the english documentation of ruby
core and standard libraries of an example of where the current model
likely leads, I think that's enough motivation to change. Consider
this situation.
Shoobie has been playing with shoes, finds the manual is blatantly
wrong and the argument order for one of the drawing methods is
different from what is in the manual. Shoes user has shoes installed,
and some kind of code editor, but they have never used svn or git or
anything like that because they're only just learning to code now.
I can't imagine that situation resulting in anything positive. At
worst it drives them away from shoes feeling left out and frustrated,
and at best it results in an email to _why which makes its way in to
the manual text on git quite quickly, but takes months to get back to
that user or anyone else because they're left waiting for a new build
to come out.
My first moment with ruby was on _why's interactive tutorial, and ever
since nearly everywhere I turn, _why has contributed something great
to that area. The first time I met _why on IRC I was very intimidated
and anxious to meet the almighty, which fortunately is not who he is. :)
So that's why I like an interactive manual app. _why may be a great
friendly guy, but new users don't know this, and they can't know this
until they interact directly with him. If we make that interaction
very easy and very anonymous, I really think a lot more people would
have the guts to face the god and bring him down to earth in their
universe, maybe becoming active members of the community. :)
If manual changes sync each day, that's a heck of a lot more
satisfying than waiting a month or longer, and many of the manual
contributions would apply to this version, not a future one. I see no
reason why the manual couldn't ask the shoooes site for updates and
include it's revision number. Then if we did go a wiki-like way, when
an update is made, it could include parameters for which versions it
applies to, and simply would never be seen by the older versions of
shoes when they ask for updates.
Another model which I really like is on each section in the manual,
have a small 'comment' link. When pressed, a window opens which asks
for a name and a comment, akin to that on _why's tumblogs. This way
the level of anonymity is up to the user and what they put in that
box. Then _why would get an email and be able to take in the feedback,
make whatever change is needed, and people's shoes manuals would
automatically gather the update over time. This takes out the problems
of wiki's and is surely much simpler to implement. Best of all, it
means people get to communicate with _why directly in an unscary way
and get to know him a little via email or even maybe a built in
comments thread in that comments dialog window.
Heck, we could even have shoes load the manual file off of github
directly, using http features to only download it again when it has
changed.
Whatever happens, I'll be happy so long as it becomes obvious and easy
to help with the docs without ever having to touch git or even know
what git is.
