directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ole Ersoy <ole_er...@yahoo.com>
Subject Re: Standardized Documentation Markup and Best Practices
Date Sun, 19 Nov 2006 19:35:29 GMT
Oh Yeah - No worries mate :-)


--- Emmanuel Lecharny <elecharny@gmail.com> wrote:

> On 11/19/06, Ole Ersoy <ole_ersoy@yahoo.com> wrote:
> >
> > Yeah - I think the point I was trying to make with
> > respect to the parser is that our documentation
> > process should follow some conventions that are as
> > simple to use as possible.
> 
> 
> The parser things was pretty much a joke, at this
> point (pretty sure it was
> a joke, wasn't it, ersin ? ;)
> 
> I think the simple conventions we should follow up
> to this point are the
> confluence conventions. They have 3 advantages :
> 1) they exist
> 2) they are publicly available
> 3) we already follow them.
> 
> Converting documentation to another format is an
> > important consideration.  For instance suppose we
> > wanted to convert it to a PDF, so that we could
> easily
> > produce a PDF book like the Maven Project /
> Mergere
> > did with their Maven 2.0 book.
> 
> 
> Sure But I think that exporting the current cwiki
> doco to pdf should not be
> a real problem right now. (except that it will
> produce a pile of paper I
> would even be very reluctant to use in the smallest
> room of my appartemnt,
> regarding the content we currently have :) (hey, no
> offense, guys ! just
> wanted to say that we are far from having the right
> content to produce a
> book, not that the current content is bad :)
> 
> So having documentation that is "Atomic" in the
> sense
> > that individual pieces can easily be moved between
> > formats and templates is important.
> 
> 
> confluence offers you that, I think.
> 
> Sure we could just write some content really quick,
> > but we could be setting ourself up for more work
> later
> > when we want to produce a MVN pdf book or
> > something....
> 
> 
> Writing a book is quite a different process. I'm not
> a specialist. Stefan
> is. Let's hear about what he thinks first :)
> 
> One really easy way to solve this is to make a
> > template that incorporates the markup and Section
> > headings for documentation with a specific
> > communication goal.  Like the Maven mini guides.
> 
> 
> Never read them so far (may be this is the reason
> why I'm so shittyy with
> maven ...) But what I would say is that, for me,
> maven is *by far* the last
> example of good documentation i'm thinking of. The
> mergere book is quite
> good, but that's a different story.
> 
> Then we can make an enumerated set of mini guides
> > covering various ADS use cases.  These can also be
> > used to drive development and capture wish
> > requirements.
> 
> 
> Mini guides lead to maxi-confusion, I think. IMHO.
> When you have something
> like 50 min-guides, then it's soooo atomic that you
> almost need a periodic
> table to understand it.
> 
> I.e. someone wishes we could do this.
> >
> > OK - Tell us how you would want that to look in a
> mini
> > guide....
> >
> > That way the documentation for the functionality
> is
> > written before the functionality and the
> functionality
> > becomes use case driven.
> >
> > Personally I prefer to write the documentation
> outside
> > of confluence, because I think confluence has to
> much
> > "Noise" on the screen.
> 
> 
> In fact, it doesn't matter a lot. The main advantage
> of confluence, for
> people like me, is that I can start some doco at
> home, and continue at
> office without having to save the text file on an
> usb-key, or sending an
> e-mail to myself. But that's just me. If you are
> more confortable with any
> other way to work, great. The main point, IMHO, is
> to write doco, which is
> the complicated part of the process ;)
> 
> So if someone were to give me a simple template with
> > cwiki markup in it
> >
> > Example:
> >
> > h1. Objective
> >
> > h1. Use Case Description
> >
> > h1. Activities Performed to Complete Task
> >
> > I'd be really happy and I could just cut and paste
> > into confluence, while also storing the
> documentation
> > in the maven project.
> 
> 
> Well, we don't have this right now. Look, as we are
> pretty naked at this
> time, what I would say is : go for whatever fits
> your need and feeling about
> doco. We will follow your proposal - being lazzy, if
> someone propose
> something, we are followers by essence :) - and if
> something needs to be
> discussed, then we will open a discussion about it
> :)
> 
> I just read on an infra thread that ASF policy for
> doco is : "Commit first,
> discuss later" :)
> 
> Thoughts?
> 
> 
> Well, this was some thoughts :)
> 
> Emmanuel
> 



 
____________________________________________________________________________________
Sponsored Link

$420k for $1,399/mo. 
Think You Pay Too Much For Your Mortgage? 
Find Out! www.LowerMyBills.com/lre

Mime
View raw message