Re: Debdoc

[erik <devvnull@crosswinds.net>]

On Tue, 25 Jul 2000, Pavel M. Penev wrote:
> On Sun, 23 Jul 2000, erik wrote:
> 
> > > >   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 ...
> 
> Right, the Q&A/FAQ section:
> In a good documentation system (like the one we are trying to create) the
> user is supposed to able to straight-forwardly find the information they
> need. In my oppinion the Q&As/FAQs are just an ugly patch to the
> documentation -

  mmm, I see your point. I guess we could leave it out to begin with - if
there is a demand for it or it seems useful later it is easy enough to add.

> >  > 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. 
> 
> Yes, though we will make the templated documentation about debdoc, won't 
> we?

Precisely - then the function of the program will serve to inform the
structure of its creation.

> 	I. Documentation Servicing:
> 		1. Introduction -- impression-creatig or also "front" pages.
> 		2. Index (TOC).
> 
> 	II. Legal:
> 		1. Credits.
> 		2. License.

 I have these in one section: <pkg-name>index.html   - purely for
conceptual organization. ( someone has commented on the use of XML)

 > 
> 	III. Application:
> 		1. Installation instructions.
 
 well, as this is initially for debs we don't really need to install do we
 ;)  - but maybe something on configuration ?  Installation however would
be in a " source" template perhaps.

 		2. Tutorial.
> 			2.1. All practical application aspects tutorial.
> 			2.2. HowTo:
> 				2.2.* A set of HowTo-s for each practically
> 				applied aspect of the application's
> 				functionality.

I would add a brief set of examples here.. as 2.3

> 		3. Full application functionality documentation.

I have 3. in technical info - separate and more detailed coverage. 
> 
> 	IV. Development:
> 		1. Programming.
> 			1.1. Scientific references used in the application.
> 			1.2. Source coding style.
> 			1.3. Change log.
> 		2. Distribution.
> 			2.1. Log of distributor's changes.
> 			2.2. Pointers to other known distributed packages.

I think this one is a good start for the general " Development "
template.

> 
> I guess we would need a complete set of these before starting to write the
> application.

 So far I have 4 that might cover things to start:

  1. Application  - simple UI introduction
  2. Development - for libs and languages ( could be sudivided there)
  3. SysAdmin - obvious I hope
  4. Source - goes with deb-src to begin with. Much more detailed and in
depth. Also a more complex template to design I think.

I have several pages of notes on general structure - soon as I get time
I'll get them organized and ship them off to you. It might be a bit much
for the list ( I understand that they like to keep the load down if
possible) so I might send it to you directly as a tarball if thats OK ?
Let me know.

  > >  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.
> 
> Well, I see: the QtEZ you are dealing with. Sorry for resending my message
> (so silly -- I recieved your answer the same dialing up when I resent my
> message, sorry, again).

Hey, no problem. I'm still tracking the list.

 Actually QtEZ is on hold for a little - but I have several other things
going on at once. Bad habit of mine ... 

 erik