-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA512 On Sat, Nov 16, 2013 at 07:21:30PM -0500, Christopher Antila wrote: > 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. I guess so many of us just use the CLI to create our works that we don't think about GUI programs. I couldn't tell you a single GUI program that would be good for creating/editing DocBook (gedit?) because I just don't use them. I'd welcome other people's experience with GUI tools so we can start recommending these to people. Same goes for Git. It really isn't that difficult to use these tools once you understand what's happening and why. Like I mentioned earlier, I think training is key here and something we're missing. Last week I started working on training videos that I'll continue to refine (I'm still sick so my voice isn't great right now). As soon as they are ready I'll start kicking them out the door and hope to get feedback. > - 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. I am unaware of the policy you referenced. We *do* want guides to be published when a release is made so that users will know that the guide is specific to that release and that information isn't old or not applicable (although once we get a huge guide together there will always be old stuff in there) but a continued development should go on. I'll use the Amateur Radio Guide as an example. If I, today, package a new amateur radio program I'll more than likely add it to the guide and re-release the current guide with a later version. That's completely acceptable and desired (release early, release often!). If something changes mid-stream please update your text! > - 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. There is definite overlap in some of the guides (installation, admin, and security to name a few). We should probably reduce that overlap and make sure the expectation is to find a certain piece of information in a certain guide. Getting an internal search engine going is also needed. There are lots things that need to be done, really. I suspect that it would be quite a lift to get us back to where we need to be. That said, I don't think it's out of the question. Would people be interested in meeting for a FAD to get some stuff done? - -- Eric - -------------------------------------------------- Eric "Sparks" Christensen Fedora Project sparks@xxxxxxxxxxxxxxxxx - sparks@xxxxxxxxxx 097C 82C3 52DF C64A 50C2 E3A3 8076 ABDE 024B B3D1 - -------------------------------------------------- -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.15 (GNU/Linux) iQGcBAEBCgAGBQJSiizHAAoJEB/kgVGp2CYvDdAL/2kuN5XaUQRchMKQBky4icxW wqHZ4qdlCx8tGKSmj8XEdo1zeTLebFkc988/pRHHDtEEEbVwrpJhhZS5t3s9htbN mYlQuGb7BGx01GSRScHc+lDwZSwO0tgcpfQ/omhVBzXi5TJlyktff4uOkcNoQwqw We2gPx/1+4b7ahcV2FDwrdBYIks3+VZaZ1FCr5bxjJuwszC2exoXHgcC1UEReniA Pbtga4l39VtfBXGDpZCx3MJiis2Wth0uxR3a2o1BEuzB8o7Jl3pgGHrtcB8U8d4/ L+WZ/6ARfip2E/N1NAFgmgqTDZWBnhkzQ22YWS7IJO+P6bRCwUoSq1RGj7lda0Lz RYdmPg2KTbm1DsPV/r9VIplv53ohGQStArT0xOt/pY5DrMMAUaqedxpyO3GcH51p rNemTk5ZxKnqoHdsq9ZeGqya0ZtUzD1TqEw6tEWrcfGs9ctK4PuBBFqI3fOxTVhY /x9uomENbCt/HDZHsd1zGxIOMhTQc9XA87UPtdcsSg== =/maF -----END PGP SIGNATURE----- -- docs mailing list docs@xxxxxxxxxxxxxxxxxxxxxxx To unsubscribe: https://admin.fedoraproject.org/mailman/listinfo/docs
