Re: Progeny Debian Manual Project - Let's Talk Content

[Osamu Aoki <debian@aokiconsulting.com>]

Yep.  Let's talk content.

 We need to make this document into _Debian_ User's Guide. 


On Sun, Apr 14, 2002 at 03:02:52PM -0300, Bruce Byfield wrote:
...
> Second, I wanted to mention that what has been down on the project in 
> the last few weeks has been formatting, largely due to the efforts of 
> Osamu Aoki. I'm very glad that someone took the lead in this effort, 
> especially so we can start to get away from the embarrassment of an open 
> source project that's dealing in proprietary formats. Also, while this 
> work is very necessary, it can drag on, so the earlier it's started, the 
> better.

Thanks.  HTML output of current version is available at:
 http://www.debian.org/doc/manuals/users-guide/
 
 I still need to refine <ref ...> tags.  Also, including modified
 original HTML as SGML comments for the table section may be a good
 thing to do.  It shall prepare for the future like XML.

> However, I am also concerned that some people might lose interest from 
> too much talk about formatting, so I wanted to raise the issue of content.

That is exactly the reason why I posted SGML before fully arguing over
formats.  File format conversion between XML and SGML are trivial thing
but we need working documents for content brush-up.

> As I see things, here are some of the areas where work needs to be done, 
> and decisions need to be made:
> 
> 1. The introduction - While some reference to Progeny is appropriate 
> here, the section needs to be rewritten to give more information about 
> Debian, and less about Progeny. In particular, an explanation of stable, 
> testing and unstable would be useful here. This is a relatively small job.

I started some editing in current SGML version.  It needs some English
speaker to make it nice.  This should be nice and compact.  (Smaller
than Install manual.  Maybe we should copy some from there.)

> 2. Installation - The Debian installation guide is very thorough, and 
> Osamu Aoki has suggested using the Progeny manual as a post-install 
> guide. However, while this section isn't a large priority because of the 
> install guide's existence, I'm in favour of the Progeny manual being 
> complete in itself . For one thing, the install guide's material would 
> be more useful if restructured in the form of the Progeny manual, with 
> enumerated steps and (format permitting) screen shots.

My point is concentrate on post-install.  Do not duplicate Install
Manual activity.

Since Install manual is too through in some respect, shorter version for
here may be nice addition.

If resource permits and some one takes lead, I love to see Install
section.

> 3. KDE references - The manual was originally written explaining how to 
> do things from the command line and from the GNOME desktop (the default 
> for Progeny). However, KDE is the preferred desktop by a ratio of about 
> 3:1, so it deserves some mention. Either the desktop sections could be 
> rewritten to refer to KDE, or KDE sections could be added.

Not that I am KDE person, I see your point.  I thought about few types of
Desktop.

1.  TWM (or Blackbox): Bare minimum
2.  GNOME-SAWFISH
3.  KDE
4.  WINDOW MAKER:      (or Afterstep)

Advantage of "Debian" is choice by the system administrator.  If some
one volunteer, I love to see them included.

> 4. Software installation - The package system is basically documented. 
> However, more advanced information could be added here. Progeny 
> references also need to be deleted.

Yes.  Have you seen "Debian reference" and "APT HOWTO" on DDP?

  http://www.debian.org/doc/manuals/quick-reference/index.en.html
  http://www.debian.org/doc/manuals/apt-howto/index.en.html

> 5. Installation and configuration - A lot of Progeny-specific material 
> needs to be replaced. Additions should include dial-up and ISDN connections.

Also Cable and DSL (DHCP, pppoe) staffs too.

> Of course, everybody is free to select other areas to work in, but these 
> are the places where content needs to be added to complete the 
> transition from Progeny to Debian in the manual.
> 
> By now, I hope that everyone has had a chance to look through the manual 
> and think about where they would like to make a contribution. So, when 
> you know what section you would like to work on, could you post to the 
> Debian doc-list or else let me know? That way, those of us working on 
> the same section can coordinate our efforts and avoid duplication. In 
> addition, I've had several e-mails asking where a contribution could be 
> made, so it would be nice to be able to answer these queries with some 
> intelligence.

I think using CVS on DDP is best way to do this.  Just make sure everyone
send patch as branch with e-mail to the coordinator (Bruce).  If someone
can not handle through CVS, I can help on that.  I can do SGML part too.

$ export CVSROOT=:pserver:osamu@cvs.debian.org:/cvs/debian-doc
$ cvs login
$ cvs co ddp
$ cp -a ddp ddp-org
$ cd ddp/manuals.sgml/users-guide/
$ cd $HOME
$ diff -Nru ddp-org ddp >users-guide.diff

Mail me diff if you do not have account or commit as branch.

> Finally, for those new to all this: Besides an installed copy of Debian 
> (obviously), it would be useful for you to know something about CVS and 
> SGML/XML. If you are unfamiliar with these markup languages, or don't 
> have time to learn them, you might want to consider teaming up with 
> someone who can help you. Also, if any veterans can suggest good 
> references on these subjects, please post them.

Boot floppy people seems to have good guideline, I thought.

I made some quick guide for "Debian reference" on 
  http://qref.sf.net/doc
Maybe useful.

Regards,
Osamu
-- 
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
 Osamu Aoki <debian@aokiconsulting.com>, GnuPG-key: 1024D/D5DE453D
.
 See "Debian reference": http://www.debian.org/doc/manuals/quick-reference/
 Project at: http://qref.sf.net
.
 I welcome your constructive criticisms and corrections.


-- 
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org