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/>
--
Suvayu
Open source is the future. It sets us free.