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". 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.
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 ;-)
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
I will find it. That's what counts for me in this case. Remember, *I* am my most important user. Or, to quote a famous saying attributed to A'rpi (world famous MPlayer developer): "More user-friendly? My software runs just fine without users!" ;-)
Now, if you drop it in the documentation directory of the particular project, then that would be the best place.
That's not going to work. Example. http://seifesrants.blogspot.com/2021/01/ethernet-on-bananapi-m2-zero.html Where to put this relatively specific piece of instructions? I'm not even sure that it's 100% correct, I am actually pretty sure that there's a better way to do it. *IF* we had a documentation repository for "various ARM SOC particularities", I could submit a paragraph detailing the issue and just ask for proof-reading on the opensuse-arm list. Quite probably, someone would just quickly submit some fixes. Then I'd hand it over to the "documentation team" for improvement of the formatting. Very easy with a git workflow. Not doable for me with a Wiki.
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. -- Stefan Seyfried "For a successful technology, reality must take precedence over public relations, for nature cannot be fooled." -- Richard Feynman