Ticket #72 (closed enhancement: wontfix)

Opened 6 years ago

Last modified 10 months ago

Wiki-like interface

Reported by: waern Owned by:
Priority: major Milestone:
Version: Keywords:
Cc:

Description

There have been various suggestions about adding a wiki-like interface to Haddock, to be able to quickly suggest improvements by editing documentation directly on the page.

The system could produce a darcs patch or diff against the current source of the documented module, based on the modification. This patch could be sent to e.g. the libraries@… list or to the maintainer of the package.

Some people have suggested that it should be possible to directly update the documentation (but not the source), with an option for viewing the current or source-based docs.

Several extensions to this can be imagined:

  • comments on other peoples comments/modifications (reddit[1]/forum-style)
  • ranking of modifications/comments (reddit-style)

The benefit of reddit-like commenting is that a suggested modification can be discussed and improved by other users reading the same doc, without having to subscribe to a mailing list. This would probably generate more discussions and more participants in discussions. For some packages, a @libraries discussion is of course always needed in the end.

Please use this ticket for discussing the design and implementation of these features! To begin with, we could discuss how to just implement a wiki-like way of editing the documentation to produce a patch.

We should also look at other similar system. One of them is Annotated CPAN [2].

[1] http://www.reddit.com/

[2] http://www.annocpan.org/

Change History

  Changed 6 years ago by anonymous

  • priority changed from major to minor

follow-up: ↓ 4   Changed 6 years ago by apfelmus

For reference, here the corresponding entry in the Haskell Proposals reddit.

Concerning the design, I'd use a classic Lens approach

    data Lens a b = Lens { focus :: a -> (b, b -> a) } 

    instance Category Lens where ...

The server side script uses a lens to cut the full source file down to haddock only. Changes to the haddock will be mapped to changes to the source file which can be recorded as patches. Using lenses to display a page can probably be integrated into the wiki engine while haddock is to provide the actual lens that maps .hs to documentation.

For more on lenses, see also Functional Forms. They call it "functional references", though. The term "lens" comes from the paper Relational Lenses.

  Changed 6 years ago by waern

  • priority changed from minor to major
  • milestone 2.6.0 deleted

We should wait with setting a milestone until someone has agreed to work on this. If anyone is interested, please say so :-)

Also, I'm setting the priority back to Major since this is actually an important feature, compared to many other enhancements

in reply to: ↑ 2   Changed 6 years ago by waern

Replying to apfelmus:

For reference, here the corresponding entry in the Haskell Proposals reddit. Concerning the design, I'd use a classic Lens approach {{{ data Lens a b = Lens { focus :: a -> (b, b -> a) } instance Category Lens where ... }}} The server side script uses a lens to cut the full source file down to haddock only. Changes to the haddock will be mapped to changes to the source file which can be recorded as patches. Using lenses to display a page can probably be integrated into the wiki engine while haddock is to provide the actual lens that maps .hs to documentation. For more on lenses, see also Functional Forms. They call it "functional references", though. The term "lens" comes from the paper Relational Lenses.

An easier approach would be to let the user edit the original .hs file (or whatever file-format is the original), but only allow changes to the Haddock markup. It might be good to be able to view the source code when editing the documentation anyway - you better know what it is you are documenting. Not sure if showing the source code is the right default, though.

  Changed 4 years ago by igloo

From http://hackage.haskell.org/trac/ghc/ticket/1064 :

It would be great if Haddock generated web pages that allowed users to add commentary to the documentation. That would make it much more interactive. The PHP manual does this, to good effect http://blog.milkfarmsoft.com/?p=29

In fact, Haddock already supports something like this. It has a flag that adds a Wiki link to every function definition; users can click on the link to get to a Wiki page that they can then add material to. But it's not perfect:

  • Most of the Wiki links will be empty, but there's no way to tell that when looking at the link. It'd be better to highlight populated links somehow.
  • The library author may want to look at all the comments for a module, with a view to enhancing the Haddock docs; but it would be unbearably tedious to go through them all one by one.
  • There is no place for overall comments

There is real potential here, but it needs someone to think about it, and implement something a bit better.

  Changed 10 months ago by Fūzetsu

  • status changed from new to closed
  • resolution set to wontfix

We have discussed this a bit today and considering that there hasn't been a whole lot of interest in this in the 5 years the ticket has been open and neither myself nor the current maintainer are interested in implementing this (and I personally think that if there are problems with the docs, they should be fixed upstream rather than having a whole infrastructure hacking around the problem), I am going to close this ticket with wontfix.

If someone does feel that this would be of great benefit to them *and* is willing to spend their time implementing it, please re-open and we can discuss it again.

Note: See TracTickets for help on using tickets.