Re: Debian reference
Let me forward this to debian-doc. This is interesting.
Just short note for David. He is the acting style editor for "Debian
reference". I am the mailing list scavenger, cvs maintainer and
bad English generator :)
I read his mail after commiting my change.
On Sun, Mar 03, 2002 at 08:37:45PM -0500, David Sewell wrote:
> On Sun, 24 Feb 2002, Osamu Aoki wrote:
>
> > All pages from FAQ, I think should be removed (support, system, faq) and
> > shall be replaced with the pointer. There is so much people can
> > maintain as volunteer.
Apparently, I had change of mind :)
> After looking over the completed "stable" (www.debian.org) Version 1 of
> our [Quick] Reference, and the latest version of the Debian GNU/Linux
> FAQ, I agree with you. I understand why Jospin suggested merging the two
> documents into a single Debian Reference, but really the documents have
> different purposes and very different structures.
Yes. I thought so then.
> The FAQ offers detailed introductions to or explanations of a wide range
> of conceptual issues, from philosophical ones ("what does 'free' mean in
> the Debian context?") to technical ones ("how does Debian package
> dependency work?"). (I'm giving examples that aren't in the FAQ in those
> exact words.) It offers a few step-by-step instructions, but not many.
> Instead, it tends to point to other manuals or documentations for
> details.
I agree, what do you think my new reorganized contents in chapter 2. I
did remove FAQ chapter which was available on sourceforge.net version.
I thought having one separate descriptive chapter will not harm as much.
> The Quick Reference mostly assumes that the reader understands the basic
> concepts. Instead of detailed explanations, he needs quick reminders or
> examples of how to do something. A "Quick Reference" is not a
> replacement for manpages and other detailed documentation.
Yes. That was my intention.
Issue of chapter 2 is some overlap with official install manual (3.0),
though.
> So I really do think you should return to the original conception and
> separate the Quick Reference from the FAQ document. Instead of merging,
> the best solution might be for you and Jospin (and other helpers) to
> look at areas of duplication in the two documents. Some repetition can
> probably be eliminated, and cross-references can be added.
As you can see FAQ section is not included now. That was bad.
Action items are:
1. reduce duplication
2. cross reference
3. separate URL into default.ent (easier maint.)
Oh, I will ask FAQ to remove Chapter 5-9 if this new version remain.
We can always do "cvs up -D ??????" if this was bad move.
> This should be discussed on the debian-doc list (if you want, you can
> just forward this message there). I subscribe to debian-doc now, so I
> can follow the discussion there.
Well. I forward CC this to there. Hope you do not mind.
--
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
+ Osamu Aoki <debian@aokiconsulting.com> @ Cupertino, CA USA +
Reply to: