Re: Debdoc
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 -- they do not contain new information but just a copy of
the sections of the docs, for a newbie user is not likely to find it in
the ordinary sections; moreover, I think it is badly organised, because:
1. You have to scan the Qs in order to find the pice of info you
need.
2. If you put too much information therein it we would become
easier to find it in the other sections.
2.1. The As' scope is very narrow (what of you need the
answer of a very slightly different question?).
2.2. The As' can not be as detailed as the other sections
of the documentation, since the reason in the 2.1. point.
> > 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.
I agree -- let's make a debdoc for now, though, make it extensible. I
myself have suffered from being unable to write the tons of additional
source code, necessary to make my application more usable.
> > 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?
> > 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.
Ok, here is what I am up to:
File "notes.abbrev.txt":
TOC Table Of Contents
EOF
File "notes.txt":
The documentation about an application should have the following main sections:
I. Documentation Servicing:
1. Introduction -- impression-creatig or also "front" pages.
2. Index (TOC).
II. Legal:
1. Credits.
2. License.
III. Application:
1. Installation instructions.
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.
3. Full application functionality documentation.
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.
EOF
Once we are sure this is complete, we could start expanding it deeper
until we reach the templates. So, patch this with your ideas.
> After this we should be able to effect a merge of concepts for a basic
> target (ie. what the system should produce ).
Right, this would be our RFC when programming.
> 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.
I think this is really where we are (and sould be) heading to.
> > 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.
I guess we would need a complete set of these before starting to write the
application.
> 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).
I try to be more patinent,
Pavel
Reply to: