Re: [generguide-devel] CVS setup for docs, and comment_ent.sh script

[Sean W. <se...@ya...>]

--- Artur Hefczyc <ko...@pl...> wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Cameron Shorter <ca...@sh...> writes:
> > generguide/docs/oper and have put Seans docs in
> there.  (Still missing a 
> > couple of dirs, not sure if they are in the right
> place)
> Did you check it in other projects? I mean apache
> projects have well
> designed and well tested directories hierarchy.
> Maybe we could take
> sample structure from their projects?

Each project defines its own. The problem is that
there is a difference between generguide and other
projects.

Generguide is mostly about documents. Other projects
are mostly about the code. The requirements for folder
structure is different. In code projects the documents
are normally kept with the code. We can do this, but I
don't think it will scale when we get to the
repository concept.

The folder structure I have suggested is based on my
own organisation. The idea is to categorize
information, hence the high-level (depth 1) names. An
information category can hold many documents. Whether
you place then in one folder (depth 1) or create
seperate folders for each sub-type (depth 2) depends
on how many documents you perceive will be collected
under depth 1. I normally create a folder per
document. This is especially useful when working with
modular concepts as it keeps the files of a book
together. I know that the files in this folder A are
the main resources for this book. I can therefore
checkout just that list of files and not have to dig
around a list of 100 files when I only need 10. The
same applies to images. The folder structure should be
like a library system found in a bookstore. So if you
want non-fiction, ingnore the fiction. If you want DIY
books, ignore the Health and Beauty section etc.

Except for very special parts of information, you will
find that there is very little content reuse between
books of different categories and sub-types. However,
in the case were a set of books is related, such as
the subject of generguide, there may be a greater
degree of reuse. Though the level of reuse is likely
to manifest itself as Xpointer to a section within an
article. Hence the structured authoring requirements.
Something that has not yet been engineered into the
USer Manual. It is part of the embelishment I want to
do to the documents.

For an idea of information classes that are part of
product development, see the attached UML (poseidon).
There is the beginnings of a class diagram that
expresses the information groups as classes and the
sub-types as operations.

Sketching in this way may help you to make a decision.

Sean Wheller 

__________________________________
Do you Yahoo!?
Exclusive Video Premiere - Britney Spears
http://launch.yahoo.com/promos/britneyspears/