Re: Debdoc
On Sun, 23 Jul 2000, erik wrote:
> > 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)
Do you mean the "index.html" is containing "1. Introduction -- ..."?
> >
> > 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.
I see what I have forgotten. Is then ok to make it this way?
[...]
III. Application:
1. Setting up...
1.1. Installation instructions.
1.2. Short configuraion instructions.
[...]
3.1. Full configuration capabilities
documentation.
> > 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
Nice idea. Though, wouldn't it be better to put them along with the
HowTo-s?
> > 3. Full application functionality documentation.
>
> I have 3. in technical info - separate and more detailed coverage.
Pleae, could you list the point "Technical info"?
> > 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.
You are Debian developer. You should know better what to put here (at
least in the "2. Distribution."). Maybe some bug-tracking information (I
know this dicussion going in <debian-devel@lists.debian.org>, but we might
come out with another soulution?:))
> > 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 good section "3. SysAdmin" that I have forgotten.
Just a note:
The structure I've supplied was about ALL a package documentation should
contain. Of course, we would then split it into different individual
entities -- some of them to go with the package, others -- with its
source, still others -- just in a separate package). I think this is what
you have listed here. Am I right?
> 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.
It is completely ok. (Moreover I think it would be better -- I would have
a separate document: no need to refernce mail messages:))
> > > 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.
... Just "Thanks".
> Actually QtEZ is on hold for a little - but I have several other things
> going on at once. Bad habit of mine ...
It is not only yours. I myself am trying to deal with mine. (You may have
noticed that I proposed a project sometime before you sent your message).
Mail you soon,
Pavel
Reply to: