[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Ozone Doc Project
On 29 May 2001 11:24:03 +0200, Per Nyfelt wrote:
> > Eric, thanks for your DocBook package, it works for me. Per, it's ok with
> > me if you think what I suggested was a bit too formal. Maybe you
> > are right;
> > a too strict approach might scare people away or tire them off after a
> > while.
>
> Yes that is my fear.
>
> >I think then we need just an overall plan (i.e. how the
> > docs will be
> > structured), so that people who want to write will have a "slot" where to
> > insert their doc in the overall project; I mean, I know now we have the
> > user/developer/admin branches; but is that good enough? How do we further
> > subdivide? As far as the developper doc goes for example, maybe I could
> > submit a very generic Table of Contents on the mailing list (of course it
> > would be incomplete, that's the point!). Other people (especially more
> > experienced ones with Ozone, like your Per) could modify/annotate
> > that TOC,
>
> Exactly what i had in mind too :) Starting with a TOC is a top down approach
> and it should be coupled with a bottom up one as well (i.e. howtos on
> certain issues, tutorials, examples etc.) then it is up to you, me and Eric
> to make them (TOC drilling down into finer grained areas and finished
> sections on certain topics) meet and make sense.
>
> > BTW, I will be able to generate UML diagrams since we have
> > Together here...
<snip>(please excuse weird formatting, Ximian evolution(cool mailer) is
undergoing weird dev stage at the moment, no enter key) I have been
checking CVS of argouml out, and althought I cannot as yet get it to
compile, (need a new ant build) it appears it may be heading for a uml
generating format, as discused, we can use Together (or Rational, or
others) but what we really need is a tool that can be automated to do
UML out of the CVS tree, it appears aroguml may be heading this way, but
it is not there yet, I agree with Per that doing it by hand would
quickly become tedious and un-fun and this is against the rules as Falko
pointed out ;), so do we wait a bit for argo to gain the features we
need or try to come up with another solution (XMI might be one, it's
just XML, so maybe we can generate it without graphics and allow people
to load XMI into the tool of their choice, I know Together, Rational and
Magic Draw all support this). Other than this, I think the TOC supported
by howtos is a good format to follow for the Ozone Doc Project, If
others have not seen the postgresql documentation, it is a good example
of a well documented open source project. As far as th way to fit UML
into this, I am definitly in favor of a limited set for users,
explaining the basic workings of Ozone, and a more involved Developers
set, which would basically cover what you would get out of Together
etc., but we also need use cases, which I feel will need some input from
Falko or one of the other SMB people who have been developing Ozone for
a long time, as it basically covers stuff they must have benn over
already, these would serve to explain some of the things you could do
with Ozone., also, I feel sequence diagrams would be useful too, as I
find these to be amoungst the most useful UML diagrams when trying to
explain stuff to others, not everything, but stuff like transactions,
RemoteDatabase creation, HOW the RMI takes place, maybe four of five
diags, would be really useful, thoughts? Sean Allen