-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 Hi: It seems to me that there are two things going on here: 1.) Many of us feel we aren't doing things as well as we could be. 2.) Many of us like our current tools. Let's ask ourselves "why" for both of those questions. Answers to the first question will help us describe our problem, and to the second will help us avoid repeating mistakes. This is my email, so I'll start. Areas We Could Improve: - ----------------------- - - There is a significant barrier to entry. DocBook is clumsy at first, and writing XML markup by hand is always a pain (maybe I'm just not using the right tools). As far as I know, the only way to preview the final output is by actually making the final output, so DocBook needs a bit of imagination. Plus, Git is not user-friendly software and most of the documentation out there targets people who are confident on the command-line. - - The fact we try to release Guides at the same time as big Fedora release can be very silly. The Release Notes and Installation Guide should obviously be tied to a release, but many of the other Guides need not be. In fact, for the Musicians' Guide, being attached to releases is counter-productive, since audio software tends to be updated as soon as it's available, but the Docs policy of waiting for a release discourages me from updating the Guide when new software is published mid-release. Further, the fact I know there are outdated sections discourages me from publishing for a new release: it's why I didn't publish the MusGuide for Fedora 17 and 19. But again, the Fedora 16 Guide became outdated at some point between the release of 16 and 17, meaning even the properly-numbered Guide for Fedora 16 was outdated for more than half of its apparent lifetime. - - Searching through the Guides is very difficult. Usually, you have to know that something is there, or at least think to go looking through the Guides, before it's possibly useful. Does Fedora have documentation for GRUB2? I don't know, but I'd have to go looking through multiple Guides' Table of Contents; it's easier to just check out the Arch wiki, and figure out differences as they appear. - - Every distribution's documentation has its stengths and weaknesses. We should be trying to help, and to seek help from, these other distributions. Even just thinking about mostly-similar distros (popular, RPM, systemd, GRUB2, and DocBook docs), we could (and therefore should) be collaborating and sharing with the openSUSE and Mageia communities. I mean this from the perspectives of tools, processes, and content. We may even be able to share a majority of content (and the translations!) across the three distros, keeping distro-specific content in branches. Or maybe not, but it's silly that nobody anywhere seems to have asked. What I Like about Our Current Process: - -------------------------------------- - - Using Git. I know I said it's not user-friendly, but for the simple tasks in the Docs workflow, if we can't write the required documentation to help new contributors, we should all just quit! Seriously though, a robust version- control system is essential. - - Using Publican. I know I said DocBook takes a bit of learning, but "making DocBook easy" is the job of another tool. We need to make sure we keep using Publican for what it does well: prepare slick documents in multiple versions. Using Publican doesn't prevent us from using additional tools *before* Publican, like LibreOffice with a DocBook plug-in for Leslie Satenstein, a Web- based WYSIWYG editor for my friend who noticed a typo, or a desktop markup application for me. - - Using Transifex. It's much easier than it used to be. When you sit down and think about the benefits Transifex provides, the two additional steps required of Guide authors are no big deal. Other Thoughts: - --------------- - - Eric mentioned his concern over losing compatibility with DocBook. For this reason, I'd like to draw our collective attention to the "pandoc" tool, which converts between all kinds of markup formats, and is already available in the Fedora repos.[0][1] If it's really good, pandoc may help us with the "what happens before Publican" challenge. - - What's the result of the mass-docs-writing experiment we ran at FUDCon a couple years ago? - - We should de-couple some Guides from the Fedora releases, and think of a way to clearly indicate instructions for multiple versions within the same document. We should also be careful not to lose old versions, for archival reasons (Git!). Maybe we could just make new sections on docs.fp.o: "Fedora" for "rolling release" Guides and "Fedora (Release-Specific)" for others. Christopher [0] http://johnmacfarlane.net/pandoc [1] https://apps.fedoraproject.org/packages/pandoc - ------------------------------------- On 14 November 2013 07:58:16 Chris A. Roberts wrote: > some stuff I'm so pleased there's a "Chris A. Roberts" in Fedora, because I'm "Chris Robert A." Now we just need is to find an "Eric Christensen Sparks!" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBCgAGBQJSiAwOAAoJEAWCcTQ3FNFMOlsP/iHkWC+azy4inSAeVDtfa+Fb CbhahhxhbRQprIsBX0+HpzmoPcrNXttOr0uLvpy2E4oEjxMW+pG+jcd2yJKCuPyl 5KWxES0kzy6xMRGVkNsJQyL9RKqL2hCFM7t2o1LWtZFc9z9nsA2XixEsw7U3jkO2 nDXHp8g/yji5TV+t1EIOj3Vq/Tv/g/PnYloO3NOl77qDblyQ0p1WwgjJlGg6Fpeu AZYSEMliWZEX9DqOLqFI2Z0l3hbvBlELsVXHebBoOb9YdWfLSfX7eDMupm3OPrwF ZQmOU+xTfjOcfe0DNTj+MLHr9QJ/YExFpDaq4UfhYO1EWP9uzNQB5UhtYoIkvYj9 wYzrtShemShJtaf1bS+sgKXmw7naqwrP+fK8A3OIyOxkJXKoEUx64bJ5xf6HDJnb NTDeqpIWAzcbaPQvF5t3r+zYFu3UdRkJZxPI7Q3M6CjtKi29sZ80WJ6QOSja4hxv kPtn6+r8LJz61RArCq1ofzVYVNprOMOCrtf8PhU8QykEk3uDPj9kMvtBXhqzCv9A ZPKARtF6oog4Swd+cwMUrzii1G2sZ3uIfeyP2tQYRlj60tPGLGbxPDr908TBb3MA 5ACSjoNFcGUE0pZOxrD+MU4TGKctMKyqxeiQA2VhfOLVEkEAJ26WfXN7/iFexTAI lBo3N6Qg+iI8vrdF4+tw =g8h7 -----END PGP SIGNATURE----- -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
