Re: Debdoc

[erik <devvnull@crosswinds.net>]

On Sun, 23 Jul 2000, Pavel M. Penev wrote:

> 
> I think we could make the "index" page contain the introduction and make a
> separate page on installlig, huh?

 Yep, I agree -had already made a note of it....

> >   5. questions and answers
> 
> This section is what, I think, we should avoid :).

 Do you mean the Q&A/FAQ section?  If so, I'm not sure I agree but good
reasoning might pursuade me. My initial thought is that this is a good
place for user input ...
 

> Would we not better create an
> (OS/architecture/distribution/etc.)-independant application, and then add
> distribution specific modules (like a few awk/perl/etc. wrappers to
> auto-fill some fields. This way anyone would be free to create and install
> a little filter for their own distribution/OS.

 In principal I think this is a great idea - in practice though it
magnifies the scope and complexity by an order of magnitude ... I think
its possible but might be easier to do after building a prototype specific
to debian. I also know that other linux distributions are working on their
own documentation systems ( I don't use anything but Unices so I can't
really comment on the rest - only so much time in the day ;)). The
prospect of learning the ins and outs of all of the various systems is a
pretty big one and I think that developing a truly cross-platform system
would (might) take quite alot of time. However, having a working format
might be the first step to that ... 
  My initial concern personally was for debian as I like it the most and
it is also the least accessable - at least initially. I install debian on
machines for people and frequently get a call the next day about there
being no "help files" or some such ... other linuxes ( and even FreeBSD )
have an immediately obvious and somewhat centralized doc system, although
the quality varies considerably.

 > And about the default content -- I think it is a great idea.

 BTW, this idea expanded quite nicely into the idea of using the
documentaion system itself as its first subject -ie. build it first to
document itself. 

> 
> I guess we would not be able to list them all until we start using it in
> practice. Therefore, it might not be a bad idea to provide a way to add a
> custom application-class template.

 I think this is pehaps one of the central points of  the system: defining
the elements of the templates. But it also seems like it is a fundamental
structure and could be reproduced ( perhaps as modules ?) manually in the
same fashion as the first couple of templates. I think we are moving into
serious structural design here - I propose that each of us begin drawing
up a basic outline defining:
	1.  The number of sections that the overall template will have and
the general subject of each.
	2.  The number of subsections  in each section and specific
subject matter therein.
	3. Some beginning  ideas on the structure of the writing therein -
ie. begin to define the notion of "structured documentation" ( or "OO
documentation" if you prefer ;)) to deal with the indexing capabilities you
described below.

  After this we should be able to effect a merge of concepts for a basic
target (ie. what the system should produce ). 

   I further propose that once we have an agreed upon definition for
these levels of basic structure that we open an account at sourceforge ( or
somewhere ) and begin to set up things in CVS.

> To tell the truth, I am not really familiar with tex, I am now reading the
> docs.

 ... see what I mean?  I only know it from "info(1)" myself - couldn't
write in it to save my soul ;-}.


> For the titling> Recall my idea of structuring the text itself? I offered
> to make each paragraph start with a sentence describing what the paragraph
> is explaining in detail. Now, if we want a summary (e.g. a short
> description), we could get all the starting sentences and put them in one
> paragraph. This way we could get a short description about every
> section. Then we could ask the user to describe each section description
> by just one sentence, and putting them together we would have a short
> description on the whole application -- which has obvious uses. Then,
> repeating the iteration, we would have a one-sentence-desctiprion of the
> whole application, and extracting the keywords from it we could get a
> sensible title. I guess we could apply something similar to get good
> titles.
 
 This is a really _great_ concept - I'm leaving it my reply for reference.

 Small note: I have some "real" work to do too ;(- don't be surprized if I
am quiet for a little bit, I'll be back soon.

Cheers,
erik