[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Install manual organization




Adam Di Carlo wrote:

> siward <siward.de.groot@hccnet.nl> writes:
>
> > Hello Chris,
> >   nice that youre working on docs,
> >   i send you a few thoughts, hope you like them.
> >
> > I think the document should start with chapter 0 : "Welcome to this
> > document".
> >   contents, warning about document problems, foreword, getting newest
> > version,
> >   indication of copyright of document and purpose of document could be
> > (part of) this.
> >   maybe some words about or from the authors ?
>
> We cannot start with a chapter 0, the SGML formatting tools
> (debiandoc-sgml) do not support this.
>
> > Apart from this,
> >   for a document containing section "getting debian",
> >   chapter title "Welcome to Debian" seems slightly premature.
>
> Explain, please.
>

  I did indeed jot down my thoughts too hastily to make them clear.
  A new attempt, at your request, was made  and it is here :

1st thought (on chapter 0) stems from my opinion that
    readers should FIRST be introduced to the document.
"chapter 0" is intended to mean "before chapter 1".
    ( I do use chapternumber 0 for my own writings in order to more
systematically number the contents )

phrase "apart from" was incorrect.
the intended meaning was : "although also using words Chapter and
Welcome, this second thought,
    which follows, is totally independent and separate from the first.".

2nd thought : by analogy with welcoming someone to your home when you
are not yet there,
    it struck me as odd to welcome readers to Debian when they havent
yet got it,
    as is suggested by sectiontitle "Getting Debian".

Both thoughts are based on following notion :
    this document is intended to be used as an install manual,
    and its structure should be derived from that purpose.
    it should let readers, who are going to exposed to a giant amount of
new information,
        access the information they need for installing Debian.
    i think this means correct, complete, efficiently accessible and
presented friendly.

Specifically :
1) document should be available to readers and have a Title,
    so readers can decide whether this might be what they are looking
for.
2) document should then state more fully what it is,
    so readers can verify that it is what they need.
    In current document, this is the Abstract.
3) It should then state what info is in it (and what info that reader
might expect here is not).
4) Then would come stating environment of document :
    its purpose, target audience, authors, etc.
    this should be brief, as it is not required for the installing.
    this would include current install manual's section 1.7 paragraphs 1
and 2.
    the full text of the welcome to debian would not appear here,
        instead it would be referenced here (with a short introduction
sentence e.g.).
        (i think it should have its own document because it has its own
purpose and because
        duplicating it to all install manuals for all arches seems a
waste.
        It is nice that installmanual provided a place for it to be
created though.)
    copyrights would also be Referenced here. (full text could be in an
appendix.)
5) then it would show readers how to access the info it contains (or
refers to).
    section 1.7 part "organization of document", contents, location of
index if one exists, etc.
6) after this would come the contents : the step by step description of
the install process (new,
improved version ).
7) and finally (conceptually) would be the outtro.
    current documents title "next steps and where to go from here" is
beautifully chosen.
    (more on its contents later).
Everything after this would be appendices, possibly grouped into a
chapter.

---

While creating this second, less cryptic, reply to Chris Tillman
question,
    and considering structure of document, i remarked the following :

Chapter "next steps..." is currently an unstructured collection of
randomly selected topics.
It contains "linux is an implementation of unix" without further
qualification,
    while specifying its quality 'Inspectability of sourcecode' would be
a great hook for a link to FSF,

    'affordable' could give reader more insight in system he has gotten,
    'community effort' could introduce links to nearly everywhere,
    etc.
Chapter also assumes some knowledge of man and info and how to invoke
them.
    more explicit description might be usefull.
My first desire after installing my first Debian was to get introduced
to the system, and
    learn basics of how to use it. A link to a document describing this
would be great.
    following that link would also allow new user to verify that system
is indeed working as it should.

Chapter "administrivia",  with its sections "about this document",
"contributing to this document",
    and "trademark acknowledgements" are not very fortunately named.
    "about this document could be renamed to "how this document was
created"
    I would prefer "contributing ..." to be called "how to contribute
..." .
    "trademark ..." seems to have a big title compared to its contents.
could it be removed ?

---

may these inflated thoughts be of some use to you,

    Siward.



Reply to: