András Major <andras.g.ma...@gmail.com> writes: > Hi Tom, > >> > To me, the documentation is the leading specification of a piece of >> > software. Anything the software doesn't do that is in the docs is a >> > bug, but likewise anything it does do which the docs don't cover is >> > also a bug. >> >> Aloha Andras, >> >> As an avocational programmer who has had the pleasure of making small >> changes to the Org-mode manual and on-line documentation, this last bit >> seems to raise the bar impractically high. Part of Org-mode's appeal to >> me is that people frequently find new, and at least to me unexpected, >> ways to use it productively. I find it interesting to see how best to >> change the documentation to incorporate the new "discovery." That said, >> the idea that the docs cover *everything* that Org-mode is capable of >> doing is wonderful and I'll be happy to chip in when I can to help you >> achieve that goal. > > I fully agree with you, but it looks like I didn't express my point > clearly enough. I'm talking about very particular behaviour when, for > instance, a certain keyword is encountered. The example in this bug > report is a good illustration: if the tag :noexport: is only supposed > to work in headlines, then I consider it a bug if it works elsewhere, > so the developers must actually make sure that this never happens. > > Otherwise, an unsuspecting new user (like myself) reads the > documentation, and accidentally tries the tag on something other than > what's in the documentation. "Hooray, it works, and what a great > piece of software this is" -- but that doesn't last long since a newer > version of org-mode behaves differently and his undocumented and > unintended "feature" no longer works. As a software user (in this > case), I want to have a clear idea of what works and what doesn't, and > if I try something and it works, I suppose it to be an official way of > doing it. Had I not filed this bug report, I might have carried on > using :noexport: on tables until, one day, suddenly all my documents > break because this "feature" silently goes away. > > By saying that a "feature" must work if and only if it is so > documented I refer to individual features (such as keywords, tags, > keystrokes, etc.), not use cases. > > András > > > Aloha Andras,
I think I understand. Would it suffice to add this disclaimer to the documentation for starters? "Features used in ways not explicitly documented here cannot be guaranteed future support." I agree with you that the documentation can be improved. I think it is good now, but look forward to working with you when I can to make it better. All the best, Tom -- Thomas S. Dye http://www.tsdye.com