Hi Chris,
On Sat, Mar 22, 2014 at 11:21:56AM -0600, Chris Murphy wrote:
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.
Is anyone from the Fedora docs team attending the newly started "Write The Docs" conference[1]? I think this is not as tough a problem as many make out to be. A few examples would be Archlinux and Gentoo; despite being completely volunteer driven distros (no backing by a company like Red Hat) they do pretty well. I personally sometimes contribute to documentation efforts for an Emacs major mode, Org mode[2]. It is definitely not easy, but it is quite possible to have reasonably comprehensive documentation.
I think the problem with Fedora is more focus on user manual/guide like documentation rather than references. We should focus on having a comprehensive reference-style docs first before jumping towards guides/manuals. In fact, in my experience if reliable reference-style docs exist (say written by experts: devs interested in docs, knowledgeable volunteers, ..), users are perfectly placed to create the manual/guide style docs.
Just a few thoughts.
Footnotes:
[1] http://conf.writethedocs.org/eu/2014/ I'll be there, if anyone is interested. [2] http://orgmode.org/