[Haskell-cafe] Re: Sparse documentation

[apfelmus]

Claus Reinke wrote:
>> Simon, if the less-talented among us (like me) want to contribute to
>> GHC's docs -- and especially documenting the libraries -- what's the
>> best way to go about this?  I'm not too comfortable with the notion of
>> just going into GHC's guts and Haddocking the comments, contributing
>> patches willy-nilly because I'd not be certain I did the job right, that
>> I explained things correctly where I had to amplify, etc.  Is there some
>> kind of documentation team we poor souls could interact with to assist?
> 
> there was the idea of using the wiki for developing documentation
> improvements, prior to actually submitting the improved texts. the
> only hint of that scheme i can find right now is:
> 
> http://www.haskell.org/haskellwiki/Improving_library_documentation
> 
> but establishing a documentation team to help organise the process
> and to define a realistic workflow (how and where to edit, how and
> who submits when its "ready", how to avoid extra work due to working in
> different formats, ..) seems like a good idea. go for it!-)

Of course, the visionary solution would be to wikify the haddocks
themselves: imagine to simply point a browser to the documentation and
edit it in-place.

I think that web-browsers are not ready for that, though: editing things
in an extra input box after being redirected to a "edit this page"
version just sucks for me, especially for the intended haddock editing.
The dream is to have WYSIWYG editing in-place (modulo keyboard/mouse
control. Mathematica's front-end comes close to what I have in mind.).
Why to learn and adjust wiki markup on a separate page? It's not
difficult but it's unnecessary and thus wasted time.

Regards,
apfelmus