Shorewall devel - Jun 2002 - Docs - Structure Musings

IMHO, our big picture challenge is that multiple explanations for
several topics are spread out over several different docs and pages One
parameter is frequently discussed in four or more places (QSG, files
reference pages, file comments, main documentation, etc.) That gives
multiple perspectives, which can be good, but can also lead to at least
the appearance, especially to a beginner, of conflicting information as
well as increasing maintenance work. As Tom has noted, this condition is
just a natural result of the way the docs have grown over time.
Presumably, part of the role of the Doc Support Group (DSG) is to hash
out "better" organization, whatever that may be. Because the QSG is an
overview, it would be best if the future structure of the whole set of
docs isn''t _too_ hazy when the QSG is redone.

Some possible design goals in this regard:
	(1) Keep the drill down layers on most topics or parameters
limited, if possible, to say, three. Something like (a) overview/intro,
(b) main doc, (c) detailed example, with the latter usually in
file-specific docs/pages perhaps. Extended presentation of special case
scenarios (PPTP, IPSec, etc.) could be part of the main doc layer,
though perhaps in a special section or appendices.
	(2) Keep the relationship of the layers and the user''s position
clearly visible to the user, so the user can more easily navigate up and
down through their chosen level of detail.
	(3) Detail accessibility, in the form of good TOC, indexes &
search is important. Although indexing can be chore, "layer control"
would help.

Ron
-------------------------------------------------------
"Stating the obvious is one of the few things I do well."
 --Anon.

On the topic of keeping the user informed of where they are, I am
always surprised when I click on the documentation tab.  Suddenly, all
the items change.  And of all the top level tabs, the documentation tab
is the only one that makes such a change.

Once in the documentation section, the tabs on the left work differently.
Some just jump between a single long document while others bring up their own
pages.  Maybe if more topics were in their own page it would be easier to
consolidate the information about the topic.

I hope we can bring a bit more consistency to each page and to the way the
tabs work.

Thanks,

-- 
Steve Herber	herber@thing.com	work: 206-261-0307
Systems Engineer, AMCIS, UoW		home: 425-454-2399

On Thu, 6 Jun 2002, Ron Shannon wrote:
> IMHO, our big picture challenge is that multiple explanations for
> several topics are spread out over several different docs and pages One
> parameter is frequently discussed in four or more places (QSG, files
> reference pages, file comments, main documentation, etc.) That gives
> multiple perspectives, which can be good, but can also lead to at least
> the appearance, especially to a beginner, of conflicting information as
> well as increasing maintenance work. As Tom has noted, this condition is
> just a natural result of the way the docs have grown over time.
> Presumably, part of the role of the Doc Support Group (DSG) is to hash
> out "better" organization, whatever that may be. Because the QSG
is an
> overview, it would be best if the future structure of the whole set of
> docs isn''t _too_ hazy when the QSG is redone.
> 
> Some possible design goals in this regard:
> 	(1) Keep the drill down layers on most topics or parameters
> limited, if possible, to say, three. Something like (a) overview/intro,
> (b) main doc, (c) detailed example, with the latter usually in
> file-specific docs/pages perhaps. Extended presentation of special case
> scenarios (PPTP, IPSec, etc.) could be part of the main doc layer,
> though perhaps in a special section or appendices.
> 	(2) Keep the relationship of the layers and the user''s position
> clearly visible to the user, so the user can more easily navigate up and
> down through their chosen level of detail.
> 	(3) Detail accessibility, in the form of good TOC, indexes &
> search is important. Although indexing can be chore, "layer
control"
> would help.
> 
> Ron