Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
El 19/03/13 05:15, Stan Hoeppner escribió: On 3/18/2013 11:37 AM, Timo Sirainen wrote: So basically you're saying that the major documentation improvement = an index listing/describing all settings. Sure, would be useful, but I don't see having time to write that anytime soon. The time issue is perfectly understandable Timo. My suggestion may not be the gold or platinum improvement to the docs, but I think it would help a lot of people, especially since most using Dovecot are also using Postfix, and since man is the standard UNIX documentation format/interface. I think some similarity/consistency would help quite a bit as many people are so used to this format. Do you have a way to simply dump all the current conf file parameter names from 2.x into a single column text file? I'll sort it and start adding the legal parameter values and writing the parameter definitions from information currently available in source and wiki pages. When I hit the point I can't find reference material for the rest of the parameters, we can dump it to a wiki page or similar so others with the knowledge can jump in and help finish it. Once it's done, myself, or someone else if they already have the experience, can create the man page from this to be included in the source. And you can create an update mechanism/batch process so that updating the 'master' document automatically updates the source man page and other published versions, making documentation updates simple when you add/change parameters. We could do the wiki bazaar style editing from the beginning, but I'd rather not. I'd like to get it started with a framework/layout and style of prose typical of UNIX documentation, for other editors to follow. The definition text prose needs to be consistent all the way through, or readers may be confused by the different writing styles of ~50 different people who may speak different 'dialects' of English or have different writing styles. This consistency is one of the hallmarks of good technical writing. Like I said previously, the one thing I'm able to contribute more than anything at this point is time. And my writing skills aren't completely horrible--I have been published, FWIW, but not recently. But my knowledge of the parameters, and a lot of Dovecot features in general is lacking. So if others are willing to contribute where I fall short, I'd be glad to give this a go and get it started, and hopefully put a decent sized dent in it so there's not so much left for others to do. Obviously you have final review/edit authority, and if you have a particular preference on writing style, etc, I'll certainly honor that. If this is acceptable to you Timo, let me know. If so send me the aforementioned file, any preferences/thoughts you have, and I'll get started on the first draft. Definitely, something like man 5 postconf would be really useful. I would like to collaborate with that, but I think that my English writing skill are not good enough.
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Tue, 19 Mar 2013 13:36:53 +0100
Joseba Torre articulated:
{snip}
Definitely, something like man 5 postconf would be really useful. I
would like to collaborate with that, but I think that my English
writing skill are not good enough.
I would be willing to assist in a project like that. If we could get a
few knowledgeable people -- including Timo -- I think it would be a
truly worthwhile project.
--
Jerry â™”
Disclaimer: off-list followups get on-list replies or get ignored.
Please do not ignore the Reply-To header.
__
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On 19 March 2013 15:20, Jerry je...@seibercom.net wrote:
On Tue, 19 Mar 2013 13:36:53 +0100
Joseba Torre articulated:
{snip}
Definitely, something like man 5 postconf would be really useful. I
would like to collaborate with that, but I think that my English
writing skill are not good enough.
I would be willing to assist in a project like that. If we could get a
few knowledgeable people -- including Timo -- I think it would be a
truly worthwhile project.
I can't code, but I can proof-read/write. And if *I* understand the
instructions/config examples you have winning documentation - the
ultimate dummy test, so to speak. So, this could be my opportunity to
contribute to FOSS.
Simon
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Mon, 2013-03-18 at 23:15 -0500, Stan Hoeppner wrote: Do you have a way to simply dump all the current conf file parameter names from 2.x into a single column text file? With doveconf -d you get all the settings and also the defaults. The docs probably should mention the defaults also. I'll sort it and start adding the legal parameter values and writing the parameter definitions from information currently available in source and wiki pages. When I hit the point I can't find reference material for the rest of the parameters, we can dump it to a wiki page or similar so others with the knowledge can jump in and help finish it. Once it's done, myself, or someone else if they already have the experience, can create the man page from this to be included in the source. And you can create an update mechanism/batch process so that updating the 'master' document automatically updates the source man page and other published versions, making documentation updates simple when you add/change parameters. Yes, definitely something that generates all the docs from a single source. There is of course still going to be some duplication with a) example config files and b) the more context-specific wiki pages. I guess once that reference doc is done, the example config could be put to web with all the settings as links to the reference. I think the reference should also have pointers to the more generic wiki pages about the subject, such as ssl_* settings having a pointer to the SSL wiki page. That pointer could be a generic small icon in the HTML/wiki version, not sure about the man version. If this is acceptable to you Timo, let me know. If so send me the aforementioned file, any preferences/thoughts you have, and I'll get started on the first draft. OK.
[Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On 3/17/2013 3:50 PM, Timo Sirainen wrote: It's the best I can do myself. I have no idea how they could be improved in any major way. They say that the software developer himself is the worst possible person to write its documentation, because he can't understand what others find difficult.. I don't know who they is. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. I would assume you do ad hoc development like most 20 somethings, coding on the fly when you get an idea, no formal definitions, no flow charting, no pseudo code, etc. Correct? If so this is 99% of the reason the documentation suffers, and this is typical of today's crop of young developers, unfortunately. For highly technical material the author is the only person qualified to write the docs. Having a 3rd party do it has a prerequisite of a Vulcan mind meld. Otherwise you talk and they type, which is slower than you doing it yourself. A few things could improve the current docs in a major way. 1. Create man(ual) documentation, preferably with 2. A man page like postconf (5) which contains every single Dovecot configuration parameter and text explaining it 3. This man page published online 4. Publish sample conf file(s) online 5. Make these things accessible from the main Dovecot page, not buried down in the index hierarchy I've always perceived the dovecot wiki docs with the hierarchical book, chapter, verse, mini how-to layout as a dessert you assemble from the buffet--a little cake, some pudding, a dab of whipped cream, chopped nuts, and a cherry on top. You end up with a dessert, empty calories, not a complete meal. You can't get full and keep going back, assembling another dessert each time. Typical UNIX documentation is steak and potatoes, veggies, and a dinner roll. You sit down, eat, and you're full. No running around collecting your food as you've got everything you need on one plate, and it's a complete meal. -- Stan
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Mon, 18 Mar 2013, Stan Hoeppner wrote: On 3/17/2013 3:50 PM, Timo Sirainen wrote: It's the best I can do myself. I have no idea how they could be improved in any major way. They say that the software developer himself is the worst possible person to write its documentation, because he can't understand what others find difficult.. I don't know who they is. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. I would assume you do ad hoc development like most 20 somethings, coding on the fly when you get an idea, no formal definitions, no flow charting, no pseudo code, etc. Correct? If so this is 99% of the reason the documentation suffers, and this is typical of today's crop of young developers, unfortunately. For highly technical material the author is the only person qualified to write the docs. Having a 3rd party do it has a prerequisite of a Vulcan mind meld. Otherwise you talk and they type, which is slower than you doing it yourself. Software needs two types of documentation. It needs overview type documentation that describes what it is. This is for the person who is looking for a product and has no idea if this specific product can meet the need. Second, it needs reference documentation that provides syntax for commands, config files, and the like. This is for the person who is or will be using the product and needs the details to use it properly for the need. Somewhere in between is documentation that point the user to the right reference section. Providing detailed documentation of a command is worthless if nothing tells me that that command is what I should use for my need. The reference documentation may well best be written by the software author who knows exactly what syntax, etc. is needed. It's also relatively (and I emphasize relatively) easy since it can be done as you go. But the overview documentation may well best be written by someone who knows nothing about it. The expert writing overview documentation may assume the reader knows things he doesn't. It can make sense to the author but leaves the reader without a clue as to what is being discussed. When the author is someone unfamiliar with the product, he asks questions until it makes sense and there is less tendancy for the documentation to assume knowledge by the reader that is not there. Overview documentation is a lot tougher to write well and it needs someone with good writing skills (not good programming skills). Particularly in the open-source world where enhancements can come quickly, it can be out of date as soon as it's written. -- Larry Stone lston...@stonejongleux.com
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Mon, 2013-03-18 at 10:33 -0500, Stan Hoeppner wrote: On 3/17/2013 3:50 PM, Timo Sirainen wrote: It's the best I can do myself. I have no idea how they could be improved in any major way. They say that the software developer himself is the worst possible person to write its documentation, because he can't understand what others find difficult.. I don't know who they is. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. I would assume you do ad hoc development like most 20 somethings, coding on the fly when you get an idea, no formal definitions, no flow charting, no pseudo code, etc. Correct? If so this is 99% of the reason the documentation suffers, and this is typical of today's crop of young developers, unfortunately. Because it significantly increases development times, and when you're basically doing everything yourself there's nobody else reading those anyway. The more complex a feature is, the more I think about it, do pseudo code and testing. For example the redesigned dsync in v2.2 required months of thinking, pseudo coding and testing. Few features in Dovecot are that complex though. Mostly coding is the easy part, while figuring out how the configuration should be done is the difficult part. Anyway, the plan is to hire more Dovecot developers and the development process is likely to change then. But now? I'm way too busy implementing things that were supposed to be finished half a year ago. A few things could improve the current docs in a major way. 1. Create man(ual) documentation, preferably with 2. A man page like postconf (5) which contains every single Dovecot configuration parameter and text explaining it 3. This man page published online 4. Publish sample conf file(s) online 5. Make these things accessible from the main Dovecot page, not buried down in the index hierarchy So basically you're saying that the major documentation improvement = an index listing/describing all settings. Sure, would be useful, but I don't see having time to write that anytime soon.
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Mon, Mar 18, 2013 at 11:33 AM, Stan Hoeppner s...@hardwarefreak.com wrote: A few things could improve the current docs in a major way. FWIW I've found the exemplary postconf(1) almost indispensable both for exploring the Postfix configuration and for applying impromptu changes.
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On Mon, 2013-03-18 at 18:37 +0200, Timo Sirainen wrote: I don't know who they is. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. I would assume you do ad hoc development like most 20 somethings, coding on the fly when you get an idea, no formal definitions, no flow charting, no pseudo code, etc. Correct? If so this is 99% of the reason the documentation suffers, and this is typical of today's crop of young developers, unfortunately. Because it significantly increases development times, and when you're basically doing everything yourself there's nobody else reading those anyway. Or actually for the larger changes I do write design docs and usually send them to this mailing list, e.g.: http://www.dovecot.org/list/dovecot/2012-February/064114.html http://www.dovecot.org/list/dovecot/2012-February/063665.html http://www.dovecot.org/list/dovecot/2010-November/055196.html http://www.dovecot.org/list/dovecot/2010-July/050832.html http://www.dovecot.org/list/dovecot/2010-January/046148.html So it's not all ad hoc..
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
I was going to just bite my tongue, but couldn't let this go... On 2013-03-18 11:33 AM, Stan Hoeppner s...@hardwarefreak.com wrote: On 3/17/2013 3:50 PM, Timo Sirainen wrote: It's the best I can do myself. I have no idea how they could be improved in any major way. They say that the software developer himself is the worst possible person to write its documentation, because he can't understand what others find difficult.. I don't know who they is. I think it was pretty obvious that he meant 'the documentation'... talk about being a smart ass. Wietse writes all the Postfix documentation himself. It comes naturally when one performs formal software development, not ad hoc, because documentation precedes coding. snip Really nice Stan. You just proved the old axiom of what happens when you 'ass-u-me'. Writing good docs may come easy to some people (I can't speak for Wietse as to whether or not this is true for him), but I'd argue that it may not be as easy as you seem to think. Too bad the rest of your decent suggestions got clobbered by the condescending attitude. And I wonder how much time you have spent helping Timo get the documentation in order...
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On 2013-03-18 12:38 PM, Ajax aaj...@gmail.com wrote: FWIW I've found the exemplary postconf(1) almost indispensable both for exploring the Postfix configuration and for applying impromptu changes. I think most everyone would agree that postfix is in a class by itself when it comes to code quality and documentation...
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On 18.03.2013, at 17:37, Timo Sirainen t...@iki.fi wrote: Because it significantly increases development times, and when you're basically doing everything yourself there's nobody else reading those anyway. From my point of view: do continue the very same way every since writing your first code regarding dovecot! I don't see that skilled admins won't be able to config dovecot with all that available information accessible by skilled admins. I honestly couldn't care less regarding all those unskilled admins, though. The more complex a feature is, the more I think about it, do pseudo code and testing. For example the redesigned dsync in v2.2 required months of thinking, pseudo coding and testing. From my point of view: no need for excuses! And, coming back to dovecot's documentation: it can't be that worse because dovecot is running at quite some numerous sites ;-) From my point of view: just continue to push dovecot the way you did and do, please, don't become distracted by discussions like that one, sigh. With kind regards, Michael
Re: [Dovecot] Dovecot documentation WAS: Re: Question regarding Postfix and Dovecot
On 3/18/2013 11:37 AM, Timo Sirainen wrote: So basically you're saying that the major documentation improvement = an index listing/describing all settings. Sure, would be useful, but I don't see having time to write that anytime soon. The time issue is perfectly understandable Timo. My suggestion may not be the gold or platinum improvement to the docs, but I think it would help a lot of people, especially since most using Dovecot are also using Postfix, and since man is the standard UNIX documentation format/interface. I think some similarity/consistency would help quite a bit as many people are so used to this format. Do you have a way to simply dump all the current conf file parameter names from 2.x into a single column text file? I'll sort it and start adding the legal parameter values and writing the parameter definitions from information currently available in source and wiki pages. When I hit the point I can't find reference material for the rest of the parameters, we can dump it to a wiki page or similar so others with the knowledge can jump in and help finish it. Once it's done, myself, or someone else if they already have the experience, can create the man page from this to be included in the source. And you can create an update mechanism/batch process so that updating the 'master' document automatically updates the source man page and other published versions, making documentation updates simple when you add/change parameters. We could do the wiki bazaar style editing from the beginning, but I'd rather not. I'd like to get it started with a framework/layout and style of prose typical of UNIX documentation, for other editors to follow. The definition text prose needs to be consistent all the way through, or readers may be confused by the different writing styles of ~50 different people who may speak different 'dialects' of English or have different writing styles. This consistency is one of the hallmarks of good technical writing. Like I said previously, the one thing I'm able to contribute more than anything at this point is time. And my writing skills aren't completely horrible--I have been published, FWIW, but not recently. But my knowledge of the parameters, and a lot of Dovecot features in general is lacking. So if others are willing to contribute where I fall short, I'd be glad to give this a go and get it started, and hopefully put a decent sized dent in it so there's not so much left for others to do. Obviously you have final review/edit authority, and if you have a particular preference on writing style, etc, I'll certainly honor that. If this is acceptable to you Timo, let me know. If so send me the aforementioned file, any preferences/thoughts you have, and I'll get started on the first draft. -- Stan
