On Wed, Dec 19, 2018 at 09:05:52AM +0100, Aham Brahmasmi wrote: > Hi Gilles, > > > On Wed, Dec 12, 2018 at 06:39:59PM +0000, mabi wrote: > > > Hi, > > > > > > I was wondering where did the FAQ section on the opensmtpd.org website > > > disappear? > > > > > > It had useful setup examples with LMTP and Dovecot if I remember > > > correctly... > > > > > > > The FAQ was inaccurate and no one step and committed to maintain it. > > > > This resulted in people mailing me in private all the time to ask why an > > example from the FAQ was not working for them. > > > > Not opposed to having a FAQ but I can't be the one maintaining it and it > > needs to be _actively_ maintained up-to-date, not just created once then > > forgotten, otherwise this means additional work for me. > > Would it be correct to say that the reason for the FAQ going out of > sync with the code is the set of changes to the grammar? >
nope, the FAQ was removed before the grammar change. grammar changes cause the FAQ to be out of sync but add-ons also cause the FAQ to go out of sync, same for examples relying on other software which may also have changes by themselves. there was example of plugging with dkim-proxy, starting with 6.5 there will be a better way to do it, if the FAQ isn't updated users will get the old way of doing it. there was also an example of using a tool for analyzing logs but log format changes, the example no longer works and if FAQ is unmaintained, users get a broken setup. an FAQ needs to be maintained, disregarding of how many changes happen in smtpd, it is a living project by itself. > If that is the case, I propose the following OpenSMTPD operating > procedure: > When the grammar changes start, hide the FAQ. > Once the grammar changes are stabilized, update FAQ, unhide FAQ. > > If I am not wrong, the new grammar is likely to persist for the > foreseeable future. As such, once the new grammar stabilizes, the need > for maintaining/rewriting the FAQ would be minimal. > > To generalize even more: > When wholesale breaking changes start, hide FAQ. > When changes are stable, update FAQ, unhide FAQ. > > An analogy would be svn lock and svn unlock once changes are committed. > so who would do that ? who would maintain the FAQ and take care of updating it ? > This would balance the need to constantly update the FAQ with the > usefulness of the FAQ in helping volks in getting started with > OpenSMTPD. > again, i'm not opposed to an FAQ, far from it. i'm opposed to doing it myself because I don't have much spare time, and i'd rather work on the code and man pages. i'm also opposed to having an FAQ if we don't have an _active_ volunteer willing to maintain it, since an inacurate FAQ lead users to ask me to troubleshoot their setup and it distracts me from code. if someone steps up to do the work, I will happily welcome the FAQ again but it needs to be someone who commits to that work, not someone that'll write the pages dump them once and disappear. -- Gilles Chehade @poolpOrg https://www.poolp.org tip me: https://paypal.me/poolpOrg -- You received this mail because you are subscribed to misc@opensmtpd.org To unsubscribe, send a mail to: misc+unsubscr...@opensmtpd.org
