Re: Debdoc
On Wed, 26 Jul 2000, erik wrote:
> On Wed, 26 Jul 2000, Pavel M. Penev wrote:
>
> > > I have these in one section: <pkg-name>index.html - purely for
> > > conceptual organization. ( someone has commented on the use of XML)
I agree on using XML and the DocBook's DTDs. (I think it's more
appropriate for a documentation than HTML).
> > Do you mean the "index.html" is containing "1. Introduction -- ..."?
>
> Yeah, at the moment I am just thinking in terms of 4 - 7 pages ( or
> sections ) as the basic overall structure. Seems to me that "1. Intro..."
> could have the bulk of the default info about authors, copyrights,
> contact, where to report bugs and so on.
Well bearing in mind the meaning of the work "index" a would rather prefer
to call this way "2. Index (TOC).". However, as we have the
impression-creating in "1. Introduction -- ..." I would say this is the
page to visit the first time you start reading. What I am trying to say is
that if we want an easy-to-use documentation exact word usage is of pretty
high importance, so I am concerned of the use of the name "index". As it
will probably be just a little annoying to see the same intro page every
time you start looking in the docs when you definitely do not need this
page. Is it not a better idea to leave "index.html" contain "2. Index
(TOC)." and create a separate (e.g. "intro.html") that would contain
"1. Intro..."? We could then add some command to the configure script in
the packages that would open "intro.html". And when you need docs open
"index.html".
> > 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
>
> Following the sort of fractal model, maybe "3.1.Full config ..." could go
> in the technical section which I see at the moment as a separate section
> that is in part simply an expansion of this section.
I prefer having a canonical hierarchy -- that would define: if one
section is an extention to another, the two sections should share a common
parent section, so that you find them the same way. As this way we would
end up having two parents of the same section, I think this is ok as
hyper-links would do a good job. The problem I am trying to solve is
that an application developer would like to have all the docs in one
place for easier maintainance (e.g. to run some wrappers on it). [1]
> > 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?
>
> oh. I thought this is where they were ... 2.2 HowTo?
Well, actually I meant (I have forgotten the dot after "2.2.*"):
2.2. HowTo:
2.2.1. HowTo1
2.2.1.1. Instructions
2.2.1.2. Example 1
2.2.1.2. Example 2
...
2.2.2. HowTo2
...
> > > I have 3. in technical info - separate and more detailed coverage.
> >
> > Pleae, could you list the point "Technical info"?
>
> A page or section of its own - it could be like the section "Application"
> that you have here but with much more specific detail. The reason is that
> alot of times one doesn't really need or understand the finer details
> until at least knowing how to use the program. This leaves the beginner
> level info in one place so that people won't get lost or overwhelmed and
> the advanced info in another place where there isn't a bunch of easy stuff
> to wade through to get to the details. More experienced people can just go
> straight to "Technical" -( if you think of a better name for this section,
> cool! hmmm, maybe it could be "Basic Usage" and "Advanced Usage")
[1]: As I mentioned above, after having a cannoncal document hierarchy, we
could just make custom (more usable) extract document hierarchies, which
would consist of hyper-links to sections in the cannonical
hierarchy (e.g. an "Exper-user documentation set" and a
"Beginner-user documentation set"). Actually this would probably make it
harder for normal users to contribute. However, users could still just
open the e.g. "Beginner-user documentation set" and work on it only, not
messing with the other docs. Please, give your view of this.
> Sections perhaps:
>
> 1. Introduction
> <see above>
> 2. Basic Usage
> a. usage
> b. configuration
> 3.Advanced Usage
> a. more detailed usage
> b. more detailed configuration
> c. some discussion of the structure of <pkg-name> in detail
> 4. Other Sources of info
> a. Instructions on how to find more info ( sites on the web,
> books, etc.)
> b. Links to other docs already provided with <pkg-name> ( man
> pages, tutorials. etc)
> 5. Comments & Trouble
> a. common problems (features :)) with <pkg-name>
> b. tooubleshooting and debugging <pkg-name>
> c. some critique of <pkg-name>, user contributed comments, some
> discussion of how to improve it
> d. TODO - and what a user could do to help
> e. how to report a bug
>
> This needs more detailed breakdown, but maybe you have more ideas to fill
> in here somewhere ? Also we might need additional section(s) for eg. a
> "Devel" template or modification of the subsections. For example, "Devel"
> might have a section on installation from source ( getting the source,
> compiling, etc) - also, if we get to a cross-platform implemetation we
> would probably like a whole section for installation. As it is though,
> .debs pretty much install themselves and how to do that is in the dpkg/apt
> docs. ( Although they really do need some work, especially apt - maybe
> we could make a nice example of a filled out template for apt-ddoc.deb,
> which has at present virtually no documentation. ).
I think we have now just faced the concepts. I guess we would need to
first aggree on something reasonable for the hierarchy.
In-fillings:
ToDo for the programme development. (I think this is what you
have)
ToDo for the programme's distribution.
Known problems (e.g. bugs, incompatabilities) in the
implementation.
Known problems in the distribution.
Hierarchal reorganisation:
Could we put section "...Administration..." as a subsection of
"...HowTo...", and then put its full explanation in "...Full application
functionality documentation..."?
> I'm actually not a debian developer officially - although I have built my
> own mini-debian custom 1 CD distibution with some extra things that are not
> in the official distribution plus some of my scripts and fixes. I have
> applied to become a developer but its a pretty slow process and it may
> take a year or so ...
I have not even applied, yet. Should I do it, in order to be able to
release our project, or you would be enough?
> > 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).
>
> Actually I missed that. What is it ( the project you proposed ) ?
Well... I have proposed the PIPI idea in debian-devel.
> Attached is a tarball with a couple of pages that sketch out just some
> of the "physical" structure and proposed abilities of the program - I
> thought also that we migh shorten the name to ddoc as it would ( in this
> scheme ) be appended to <pkg-name> to name the .deb. Same thing could be
> done with rpms, BTW. Only the extraction of the default info would be any
> different.
About the tarball> In my oppinion, you have done it impressively (I think
I should leave this part to you, I think could never do it that
well). Just one question: if we are going to implement the idea of
structured paragraphs for title generation, it would require some user
interaction; so how would you solve this (maybe several doc-building
passes)?
About the "ddoc" suffix(infix?)> I consider this just the right way to do
go. We would just keep to the already used way of handling docs, and just
provide an alternative.
> of course, being a better sysadmin than a programmer I think of the
> practical aspect first ... ;-}. But its good that we are approaching this
> from different angles.
You are really right. I seem to always look at the non-practical side of
it, whereas you are much practical. (And it's true I'm rather a la Bill
Gates system administrator, but I follow the Linus Torvald's coding
style).
> I have more notes on the conceptual structure - I have to organize them
> some and then I'll ship them off to you. I think that this part is the
> most interesting part and some ways the most important - but I think
> maybe we should take our time with it and really try to get the idea well
> refined. Once we have the general structure we ought to be able to begin
> actually hacking it out - then the process of refining the conceptual
> structure can also go on into the future ... this way we can produce a
> working and useful piece of software and then refine the theory of
> structure in documentation with a practical package already working. I
> also think this will probably go in woody (unstable) and therefor not be
> part of stable for quite awhile so we have time to really do a good job of
> it. What do you think of that ?
I think this is just the best to do. As I mentioned above we are already
starting to depend on that.
> I have to go try and save an aging server ... more later.
I know you would do it, though good luck :),
Pavel
Reply to: