Re: [xmonad] Re: Contrib Documentation (was Webpage information and a (practical) tour of the Xmonad Contrib)

Roman Cheplyaka wrote:

* Ismael Carnales [2009-01-26 06:58:26-0200]

...

Secondly I'm starting a doc that pretends to be a guided tour lookalike of some of the XMonad Contrib, I'm starting this mainly because I think it's very difficult for newcomers to discover what extra features XMonad provides. Haddock documentation is pretty useful when you know what you are looking for, but when you're looking around to find if some feature is implemented already, the way that the documentation is indexed (by alphabetical order) doesn't help much.

The in progress document is located here http://haskell.org/haskellwiki/XMonadContribTour and all are welcomed to contribute/comment/correct/etc.

Great idea, but I'm not sure about the style. Why not just give list of modules and problems, which they solve? It would be much easier to update when new modules are released. OTOH what you're doing is more like Tips and tricks, why not to add it to apropriate page [1]?

1. http://haskell.org/haskellwiki/Xmonad/General_xmonad.hs_config_tips

In this vein, we also have XMonad.Doc.Extending which is a bit of a pain to keep updated. It might be nice to script generating its content from the contrib modules' initial description comments. This would make it more wordy, but possibly the automation of maintenance and extra information would be worth it. For example, for Actions.CopyWindow, the following would be generated: * "XMonad.Actions.CopyWindow": Allows you to run internal xmonad commands (X () actions) using a dmenu menu in addition to key bindings. Requires dmenu and the Dmenu XMonad.Actions module. Some module comments are much longer, so the script could use only the first paragraph rather than the whole module description. If I ever get around to trying it, will post examples for feedback before creating a patch. -- wmw