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. -- users mailing list users@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe or change subscription options: https://admin.fedoraproject.org/mailman/listinfo/users Fedora Code of Conduct: http://fedoraproject.org/code-of-conduct Guidelines: http://fedoraproject.org/wiki/Mailing_list_guidelines Have a question? Ask away: http://ask.fedoraproject.org
