![](https://seccdn.libravatar.org/avatar/77cb4da5f72bc176182dcc33f03a18f3.jpg?s=120&d=mm&r=g)
On 08/08/2021 16.58, Stefan Seyfried wrote:
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.
Often, in the wiki documents, this is not how it goes. The documentation is or was written by a fellow user that went this road before, and documented it for others following. He is not the maintainer, so he has no idea if the code was fixed or your hardware is different. The people to ask would be the coders that wrote that code, if they are reachable.
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?
Yes, you should get an email.
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 ;-)
But no user will find it there :-p Now, if you drop it in the documentation directory of the particular project, then that would be the best place.
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.
In text, a wrong instruction is an entire paragraph with maybe a hundred words. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))