![](https://seccdn.libravatar.org/avatar/77cb4da5f72bc176182dcc33f03a18f3.jpg?s=120&d=mm&r=g)
On 08/08/2021 18.57, Stefan Seyfried wrote:
On 08.08.21 18:13, Carlos E. R. wrote:
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.
But he can answer if this "strange paragraph" in the documentation is still relevant or if he just did forget to remove it 5 versions later when it was no longer relevant.
The people to ask would be the coders that wrote that code, if they are reachable.
The developers most likely do not have the specific hardware at hand so they cannot answer if the workaround is still needed.
But don't get hung up on this example.
My opinion is: "Finding out easily who wrote what is useful" Your opionion is: "No, that's totally useless! Nobody would ever want that".
No, I never said that.
I am not going to contribute much to Wiki documentation anyway, so I don't care too much. I *think* that it could be useful if some documentation would be (at least co-)written by the developers and packagers that actually know a lot about the software the docs are about. But -- at least for me -- I will be totally repelled by having to use arcane tooling like web editors for wiki pages, or not being able to easily compare different versions and check for the latest changes.
So good luck with your docs, I probably won't need it anyway.
That's fine! :-D Really, a writer, in this case a wiki writer, loves when the developer documents his stuff. We really do. As long as we can find it. Then all we have to do is link that document, if hard to find; and perhaps complement that documentation with "guides for dummies" or examples for those people that don't understand that documentation. Or, if the documentation is perfect, then fantastic, nothing to write. Just the link. And no, I do not like the wiki editor. I use it because it is there when I'm sufficiently motivated to write something.
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.i
I have written on a few wiki pages, also on the openSUSE wiki, but I never got an email regarding the openSUSE wiki (just looked in my archives of the last 10 years). So either nothing was ever disputed in a talk page or I do not get notifies. Not that I'd fear of missing anything ;-)
I got some. Two in June, two in May. Not from the talk page, but about modifications. ...
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.
Still, if you mix up /dev/sda with /dev/sdb in text, havoc may ensue.
True. So, when someone mentions in somewhere I read that there is such an error in such page, I go and edit it instantly, even if I'm not the person that wrote that. -- Cheers / Saludos, Carlos E. R. (from oS Leap 15.2 x86_64 (Minas Tirith))