On Mar 22, 2014, at 7:28 AM, Timothy Murphy gayleard@eircom.net wrote:
Joe Zeff wrote:
Fedora, OTOH, is a much more geeky distro designed as a test bed for new ideas, programs and technologies that's not for people who don't like to tinker with things or who aren't willing to accept that not everything in their distro is really ready for prime time.
I'm afraid this "bleeding-edge" metaphor is often used as an excuse for missing or poor documentation. Official Fedora documentation is excessively verbose, and not good at answering - or even considering - issues and problems that users are likely to face.
Verbosity is a common problem in technical writing. It's easy for experienced, knowledgeable technical users to just do brain dumps. It's hard for them to adopt prose. It's probably harder still for doc team leaders of a volunteer system to be good editors which means often brutal conformance to the prose standard. It can mean simply not using a LOT of material, which then limits the type and number of documentation contributors. It's not an easy problem to solve.
As published author who was insanely verbose (see these emails, and imagine them being 10x longer), I learned that establishing prose and scope is critical. And you can't take anything personally, or expect to get any feedback or justification on your writing style. That's just too much coddling. So you'd only get into documentation as a totally selfless thankless act because that's the core job description.
Getting people who are good editors, and writers who are totally content with maybe 90% of their content being completely rewritten or tossed, is a tough combination to find in a volunteer project I think.
A major barrier to getting me to contribute to docs is that I'm totally unfamiliar with the publishing tools used and have zero interest in learning them. So I don't know how that gets worked around, or if it's just one of those filters like an LSAT or MCAT. It is possible to effectively contribute by filing bugs against documentation, and I do that. So I suggest filing bugs if you come across something that's really wordy and just not conveying what needs to be conveyed.
There is - or should be - a big difference between a Reference Manual and a User Manual.
As an example (at random) I'd take using a USB stick for installation. Does anybody nowadays actually burn CDs or DVDs? Yet finding instructions on the use of USB sticks (and external USB drives) in the official installation manual involves jumping around from chapter to chapter.
I suggest you bring your concerns to the Docs team email list, if for no other reason than they understand people do care about this sort of thing, and what the pain points are. It's no different than any other kind of criticism of software, or a bug report. In fact most of my doc contributions are in the form of filing bugs because I'm familiar with that entry method and I'm unfamiliar with the tools they use.
Chris Murphy