On 11/18/2013 04:05 PM, Eric H. Christensen wrote:
-----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.
Gedit has built-in support for DocBook and is shipped with a complete
set of snippets for this language. I don't think it can do much more though.
Vim users can use two of my plug-ins: enhanced DocBook support with
updated syntax file, improved auto-detection, and omni-completion for
both DocBook 4.5 and 5.0 (omni-completion is something like DTD-aware
editing), and my complete set of snippets for DocBook 4.5:
- https://github.com/jhradilek/vim-docbk
- https://github.com/jhradilek/vim-snippets
My configuration file for Vim can be found here:
- http://www.blackened.cz/dotfiles/.vimrc.html
Emacs users with nxml-mode enabled can use my complete set of snippets
for DocBook 4.5:
- https://github.com/jhradilek/emacs-docbook-snippets
Similarly, my configuration file for Emacs can be found here:
- http://www.blackened.cz/dotfiles/.emacs.d/init.el.html
- 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.
We are trying to reduce the overlap between the System Administrator's
Guide and Installation Guide, but it is a slow process, because both
these books are quite old and large.
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-----
--
Jaromir Hradilek
Supervisor, Content Services
Red Hat Czech, s. r. o.
Purkynova 99
612 45 Brno, Czech Republic
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
