Are Fedora docs readable?

[Karsten Wade]

On Tue, 2005-05-10 at 11:39 +0100, Timothy Murphy wrote:
> Tommy Reynolds wrote:

> I think you will find there is only one document in the universe
> called usb-hotplug-tutorial.
> I found it at
> <http://www2.frields.org:8080/WebSVN/listing.php?repname=fedora-docs&path=%2Fusb-hotplug-tutorial%2F&rev=0&sc=0>
> together with a Makefile.
> I said "make" and received a plethora of errors.

> Although some of the errors seemed to refer to DTDs,
> it appeared to me that the overall error was that
> I was not in the right context to process this document.
> My question was, what is the right context?

Those files were originally written as part of a documentation module.
If you look inside the Makefile, you'll see a need for a number of
directories to be present at ../.  The files are valid XML and will
parse with the standard DocBook DTD.  No special tools are required
outside of what ships with Fedora Core.

Although not as easy to tell in the XML, this document was written for
Fedora Core 2, documents an older method for handling USB hotplugging,
and was never formally published.  This is why you found it in an SVN
sourcecode repository instead of converted to HTML and posted on
http://fedora.redhat.com/docs.

> The question was not really about this specific document,
> but about the whole series of Fedora documents.
> 
> In my view, if something appears on the web
> with the word "document" in the title
> then it should be possible to read it,
> and if it is not immediately clear how to do this
> then there should be instructions given on how to process it.

I do not see the word "document" in the title.  Aside from that, your
argument is specious.  This is open source software we are using, the
ultimate documentation is _always_ the source code.  Your inability to
understand it does not make it any less valid.  Sorry if that is harsh,
but it's a common truth.

Our standard document template could contain some directions on
obtaining the sourcecode for the document.  The directions currently on
http://fedora.redhat.com/projects/docs will also work, as well as these
from the Documentation Guide:

http://fedora.redhat.com/participate/documentation-guide/ch-getting-files.html

Other chapters explain thoroughly how to work with the XML.

BTW, the Documentation Guide is the first link for the Google search
"how to build Fedora documentation."

FWIW, you most likely can run 

  docbook2html usb-hotplug-tutorial.xml

and receive a nicely formatted, black-and-white HTML file.  xmlto also
works nicely.  A well considered Google search such as the following is
helpful:

http://www.google.com/search?q=how+to+convert+docbook+to+html+in+Fedora

> The question was a general one, as above -
> how does a USB device decide which driver to use?
> But if you are able to answer this in my specific case
> I would be very grateful.

End user questions are best asked on fedora-list, this list is for
discussing Fedora documentation.  Ol' Tommy threw us a red herring by
trying to answer your technical question. :) Your comments about
usability are appreciated.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050510/17615656/attachment.sig>