On 08.08.21 15:34, jdd@dodin.org wrote:
In a doc, there should not be any "context specific" that is not immediately obvious, so you can change it asap.
One example: You document a workaround to get something working (let's say your bluethooth adapter). One year later, I come around and find that I do not need your work around to get bluetooth working. But was it fixed over time or is it just that my (slightly different) hardware does not nee the workaround yours needs? The easiest way would be to ask the original author of the hint. Finding this person easily is a good thing. Having to go through lots of changes, maybe with not too eloquent changelog messages, is cumbersome.
If you are uncertain of the fact, drop a note in the discussion page for others to see...
Personally, I think the discussion pages are a horrible way to report bugs in a page. Does one even get notified if someone writes something on a discussion page? And how? All the inferior tooling is one of the reasons why I never invested much time into documenting stuff on wikis. Having to use bad tools makes me avoid the work that should be done. So simple. Now I am mostly a developer type of guy, means: I don't really need that documentation. If something does not work, in the worst case, I just look up the problem in the source code ;-) But sometimes when I find a solution to a problem, I actually think about documenting it for others. But in a Wiki page? Where I later probably can not even find it again? No way. In the worst case (for the rest of the community), this documentation just lives on in ~/doc/interesting-problem-with-xxx.txt in my $HOME folder. In the not-so-bad case, I write about it on my blog (which has the additional benefit that later I can find it with any internet search engine ;-)
it's easy and harmless to change some words in a *doc*, it's absolutely not the same for *code*, where a single comma can kill an application
A single wrong instruction can render documentation useless as well, the difference is smaller as you think IMHO. The wrong comma will likely be found by a syntax parser and is obvious and thus easy to fix, but a newbie with wrong documentation about repartitioning his drive might well risk lost data. -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman