Hmm, it saddens me that I've missed this much of the thread already.
Shame on me for not checking my email at 1am!
In what ways will your book be different than the fat manual SuSE
distributes with its boxed sets? May I recommend that you reserve a
chapter, or maybe an appendix, to sort out some of the various
distributions' idiosyncracies? E.g. "Appendix A: Debian" might include
some insight into apt and synaptic, the Redhat appendix could have some
tidbits about the RHN, and so on.
Regarding the previous discussion about the state of open-source
documentation, my opinion is that, while it tends toward the highly
technical, its existence and quality varies widely. The mplayer docs, as
an example, are filled with video- and encoding-related terms that most
likely wouldn't be comprehended by some guy who just wants to play the
.asf clip that his third cousin emailed him. On the other hand, the user
guide at gnucash.org is beautifully written, with simple explanations of
concepts and oodles of screenshots. On a still different hand (can I
borrow one from someone?), the install docs for gnucash are spotty at
best, and gnucash is one of those apps that can be hours of fun to
install!
<rant>
This is, imo, the result of a general malaise among developers, especially
OSS developers, who tend to consider themselves ubercoders only seconds
away from being freed from the matrix[tm]. One of the results of this
malaise is that documentation has become an afterthought.
In the previous proprietary software model(s), coders would reach a
feature milestone, then the code would be frozen and docs would be
written, then there would be a release. With the fast evolution and
distributed nature of open-source development, however, this methodology
can only lead to disaster. By the time docs are written or updated
following a code freeze, there are already releases or prereleases of a
newer software version to which at least part of the new docs no longer
apply.
Here's my call to action: make documentation part of your source tree, and
develop it in tandem with code. Document new features AS you are
implementing them, not 6 months later when you are finally done tweaking
them. Put your manuals in your public CVS tree so that other people can
check them out, review them, and submit patches. On the same note, when
you submit a code patch to a project, send the corresponding documentation
patch as well. All these suggestions really boil down to one thing:
documentation and implementation have to become equally important parts of
the open-source development process.
</rant>
Levi
This archive was generated by hypermail 2.1.3 : Fri Aug 01 2014 - 20:05:59 EDT