On Sun, Apr 08, 2012 at 12:36:48AM +0200, Michael Großer wrote: > Thomas Adam wrote: > > On Fri, Apr 06, 2012 at 11:59:26AM +0200, Michael Großer wrote: > >> It seems like nobody is working on a book > >> right now. > > > > I am. But haven't got very far. > > > >> I have planned to write some kind of FVWM documentation > >> in English, but I only have one day per week, and this > >> day involves the four topics > > > > Why? Just put your efforts in augmenting/improving the **existing** > > documentation, such as the man pages. > > > > -- Thomas Adam > > > > At least, I plan to document how to install current FVWM versions > on Debian systems. This isn't something that fits into a man page.
You're right, it's also something best discussed with the current FVWM maintainer, and should you care as much as to take it further, the debian-mentors list. But documenting how you install current FVWM on debian? Don't bother. Seriously. It's a waste of your time. > Also showing the sources of the existing documentation (man pages, > ...) could be a good idea. I don't plan to replace the man page. > It makes more sense to show how to use the man page to write > a useful config, which matches to a certain use case (defined by > me). Hmm -- a "me too" which may or may not be applicable to someone else? To be honest, they're the worst type of documents to read because you're detailing something specific or esoteric that it's likely never going to be useful to anyone but you. Fine -- maybe others will draw inspiration from it. But to then think that showing people how to read or use the man page isn't patronising is curious -- how are you going to phrase that such that you're not also stating the obvious? You might as well host an aside tutorial on how to suck eggs. I'll happily forward that on to my grandmother. Don't you see? I'm actually giving you more than one opportunity here to augment the man page -- and no, I don't care if your tutorial style document is simply a "here's what I did" document, but if you're also including teaching people from the outset how to use the FVWM man page, that to me says there's room for improvement, albeit with supplementary explanations or some kind of example sections (which we already have for some commands anyway). Not that I'm forcing you, Michael, but these "go it alone" sorts of documents are utterly harmful to projects like this, where one-time "wow, I did it!" documents which are written once, and then never run again, just stagnate and either teach bad habits or then just no longer work. Not quite in the same vein, but look at Perl. That had a recent binge on perl4 documents to try and make "modern perl" tutorials. That will suffer from the same basic premise though of stagnation, but the official documentation never has, and that's where most people should be heading anyway. > When I actually start producing documentation ready to publish, > I can decide in the respective given case if I put it into my > own documentation or if I augment/improve the man page. That would be good. -- Thomas Adam -- "It was the cruelest game I've ever played and it's played inside my head." -- "Hush The Warmth", Gorky's Zygotic Mynci.
