-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 14 February 2013 11:28:31 Brendan Jones wrote: > On 02/14/2013 01:37 AM, Christopher Antila wrote: > > I'm obviously supportive of any attempt to improve documentation of free > > software, but we have to keep in mind that this is Google Summer of Code, > > and they only want "code"-centred projects. When I wrote the Musicians' > > Guide, it was part of Fedora Summer Coding, in a year when Google wasn't > > involved. > Well it could very well be a coding project. Think of "packaging" the > musicians guide with project files and sample templates. I really don't see this going well, unless... > It could even be interactive (ie. clicking on a link would launch said > software with packaged project file etc). ... unless somebody comes up with a truly excellent idea like this one. > I'm thinking this is probably a project which other distro's could use > as well. I've been talking to the UbuntuStudio maintainer and he is keen > to link to our stuff as well, Okay, this is starting to look promising! > so perhaps we can float a project that requires building and installing the > docs + project files + samples in locations defined by what you pass to the > makefile. That's where the coding component would come in - packaging is > considered coding. It is?! Well even so, this "packing" thing is a pretty boring project. But why do you keep talking about packaging, anyway? > Here's what Len Ovens, one of the UbuntuStudio maintainers had to say > about the Musicians Guide: > > "It is far more detailed than any of our documentation. A great job. It > certainly makes me realize how far I have to go in documenting things." Wow--I'm flattered! > Seems like a shame to duplicate effort. I certainly have used the Arch > Wiki many times to obtain the perfect audio setup. I've used the Arch wiki on many an occasion too (though strangely never for audio documentation). > Be great to have documentation which is dynamic, interactive and that caters > for different distro peculiarities. Yes, and this is again the beginnings of your great idea. > I pretty much know nothing about documentation. How does it work for > Fedora, can you explain the workflow? For the Musicians' Guide, it generally goes like this: 1.) Have an idea and decide how to write it. 2.) Write a text-only draft of the idea. 3.) Put DocBook XML tags in where appropriate. 4.) Copy-and-paste into the appropriate section. 5.) Send the document for translation. 6.) Use Publican to generate the various output formats. Fedora documentation is usually published in four formats: HTML, HTML (single page), PDF, EPUB. Publican supports other formats. One result of this is that the same DocBook source code is used to generate all the formats, so we are advised against things that are only effective in one format. An example of such a thing is that we write out the whole URL rather than "click here," because somebody printing a PDF obviously can't click on paper--they would need to type the whole URL. For documents that interest Red Hat, there's a more complicated process involving paid writers, editors, and translators. > > Also, I just noticed that---although I published it and it is technically > > available---the Fedora 18 Musicians' Guide isn't properly listed in the > > menu on Fedora's Documentation website. I'll see what I can do to fix > > that! > I did notice that. Thanks. It's fixed. - ---- And finally, here's the idea Brendan inspired. I think any packaging attempt is going to end badly because of our limited resources, and the reality that well-maintained packages require periodic, dedicated maintenance. Not to mention our "cross-distro" aspirations. But there's a better way. We could develop a web application that dynamically adjusts for distribution choice and integrates multimedia content. We could host it on Red Hat OpenShift. We could have the student develop an extension/module/something for Publican that would generate this web app automatically from pre-existing DocBook XML files. Obviously, this wouldn't be able to launch applications on a desktop computer (yet). But there are several important advantages: - - developing for Publican is a significant coding project, - - all DocBook-format documentation could be built into a web app, - - it's cross-distribution, - - it doesn't involve packaging (although Publican does already output RPM packages of documentation). Christopher -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.19 (GNU/Linux) iQIcBAEBAgAGBQJRHaPCAAoJEGpo1cWDqVnYsB8P/1jc0nXNmlyCUJkc+yDuyozZ ic8ja+VmtTQCm48dOCU+TjBElbJ9OfGm0tzdYvEtJlokWgqgxZ1397fWP0RJ4EEu pgkld+wvznxT2x3FYFJihCcdEcU6+Vs6wKjTpOgAW2cNGUg46CSjCai2k2TGoSoJ 3mJI9b0W1XYZevM3NpiKBuHGZUu2RDtr+M1IQ+WuhHfj3Mxd74zpxFCLy76vRq34 5LZrBYq1bY2mb5rU5VbJhfyvtm0CqreaHhp9/6gqtodyjI6SHtZcQaulw4i2VzDp gUgdyCoxOCbr9XeaSrithWDoOP/YXiQSpwafYdVRbApsyNHl580FVeLL+CvLWEdD 8YgWbqSu3sWTln+CLg4GSo+iz8hsl048+6jYwFksHW5LZEZXmXLEvrZbkrSTEjcm Sma4QdyQIrf1zLxk7jd02L+2uDscrW2OU7/dTvrXjwVXlt7o51r9BBMmPo4Wwm6O FYEm7vkCzqilYVaO0TTDEO7N8bVrM+uAOY2312tz3IWNngNJYKEVC70oG7TJ11su RV3uB7MsM3MoYXwhXpfbk+RdxlDc/rSSpJz3N6gWuQivxtW6Yvijjazl1CNIZlxm YDM2NBAsf6ISvN9u0s2CQop1jFMRRkzItuOM3ds0weHiIKpOzCnQIdJI4Hx52q7g 2cYwDtO2tZKi/OJmbJC6 =GhvG -----END PGP SIGNATURE----- _______________________________________________ music mailing list music@xxxxxxxxxxxxxxxxxxxxxxx https://admin.fedoraproject.org/mailman/listinfo/music
