On Fri, Apr 9, 2010 at 9:46 AM, Ivan Lazar Miljenovic
<ivan.miljenovic@gmail.com> wrote:
Job Vranish <
job.vranish@gmail.com> writes:
> I vote for adding a feature that would let people post comments/code
> snippets to the documentation of other peoples packages :)
Yep.
> It would be even nicer if you could post comments to individual haskell
> definitions on the haddock page, and then hide most of them by default under
> an expander of some sort.
Rather than, you know, providing the maintainer with a patch with some
improved documentation?
This is often more difficult than it sounds. The biggest obstacle to this approach is that a new hackage version of the package must to be uploaded to update the documentation and the authors (me included) tend to prefer to push new packages only when there are significant changes.
Steps involved currently:
0. pull down package source to build manually
1. add documentation/code snippet to source
2. build haddock documentation
3. debug bad/ugly syntax / missing line breaks that break haddock
4. generate a patch
5. email patch to author
6. wait a week for the author to actually get around to applying the patch to whatever repository the source resides
7. wait several weeks for the author to release the next version of the package
Steps involved with mini wiki:
0. add [code] [/code] tags (or whatever)
1. copy
2. paste
3. submit
I think making this process easier would greatly increase the community involvement in the generation of documentation and improve the quality of the documentation as a whole.
I would imaging that this would not be a trivial task, but I think even something super simple (like what they have for the php documentation) would be much better than nothing.
- Job