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:24:17 GMT
So,

To simplify all the stuff I just said :-)

Here's my recommendation for documentation production:

A) Write the documentation in the cwiki format
B) Extract a template out of the format (Sort of like
extracting an interface from a java implementation
file)
C) Make the template the standard for writing that
type of documentation that you just wrote.
D) The first documentation that you just wrote becomes
the example for how to use the template.
E) Supply the template along with template writing
conventions like these:

http://www.mozilla.org/contribute/writing/guidelines

Benefit:
We can easily create a "Model" that fits the template
so that the content can be reformatted and inserted
into other documents (Book PFD, Apache Site, Eclipse
Documentation System, ADS Wish List to Code system,
etc.)

Risk:
If everyone does the documentation their own random
way then to achieve the benefit listed we could end up
tripling to quadrupling the total effort required
(Probably a conservative estimate).  Just imagine if
Stefan writes one document one way and Ersin write
another document a different way and we want to
consolidate it and put it on the Apache site so that
it looks professional.







--- Ole Ersoy <ole_ersoy@yahoo.com> wrote:

> One more example consideration that Stefan
> mentioned.
> 
> The Content needs to go from the wiki to the main
> apache site...eventually...
> 
> How does this process happen?
> 
> It should have some simple rules so that it could be
> automated.
> 
> So if all the content is captured in a standardized
> content model, it makes this easy.
> 
> In order for this to happen there needs to be
> content
> model that backs up templates we are using.
> 
> There can be mini content models ... one per
> template.
> 
> This lets us focus on each template and how to map
> it
> to the target media we want the content to go to.
> 
> This also lets us focus documentation guidelines on
> a
> template, thus minimizing the amount of effort spent
> learning to write documentation with a specific
> goal.
> 
> So if we do this we maintain maximum flexibility for
> future content mapping and transformation
> requirements, and we end up with easy to write and
> manage documentation.
> 
> 
> 
> --- 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.
> > 
> > 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.
> > 
> > So having documentation that is "Atomic" in the
> > sense
> > that individual pieces can easily be moved between
> > formats and templates is important.
> > 
> > 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....
> > 
> > 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.
> > 
> > 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.
> > 
> > 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.
> > 
> > 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.
> > 
> > Thoughts?
> > 
> > 
> > 
> > 
> > 
> > 
> > 
> > 
> > 
> > --- Emmanuel Lecharny <elecharny@gmail.com> wrote:
> > 
> > > Well, in a previous mail, Ersin wrote that the
> > > *most* important think is the
> > > content, not the format :)
> > > 
> > > We won't change the format every month, so far.
> We
> > > are now on cwiki, which
> > > is confluence, and I also think, as Ersin, that
> > the
> > > current doco sucks, is
> > > incomplete, and is not well organized. Whatever
> > > format we use :) So I think
> > > that I don't care if we don't have the Super
> Magic
> > > Format Converter, I just
> > > try to do my best to add some doco, using the
> less
> > > possible markup (just
> > > some h1., h2. whatsoever), not because I'm
> worried
> > > by conversion problems,
> > > but because it takes already a _lot_ of time to
> > > write some doco that I don't
> > > want to spend more time learning about all the
> > > possibility offered by
> > > confluence.
> > > 
> > > Hey, we are writing a Ldap Server, not a generic
> > > tool to convert wikis,
> > > aren't we ? ;)
> > > 
> > > Emmanuel
> > > 
> > > On 11/19/06, Ole Ersoy <ole_ersoy@yahoo.com>
> > wrote:
> > > >
> > > > Incidentally I found this project:
> > > >
> > > >
> > >
> >
>
http://www.usemod.com/cgi-bin/mb.pl?WikiMarkupStandard
> > > >
> > > > Its focus is on Standardized wiki markup and
> > > easing
> > > > transition and learning between various markup
> > > > semantics.
> > > >
> > > > One of the things it mentions is using a
> "Lowest
> > > > Common Denominator" set of tags to ease
> > > transition,
> > > > which we may want to consider.
> > > >
> > > > True we can just write a parser for the cwiki
> > and
> > > map
> > > > it to whatever, but this could end up being a
> > > bigger
> > > > than anticipated project with (special mapping
> > > rules
> > > > to account for various differences in the way
> > > > submitters wrote the doco) if at some point in
> > the
> > > > future we wanted to convert format.
> > > >
> > > > Some documentation automation should be a
> > > requirement
> > > > I think...like automating "Figures" numbering,
> > > heading
> > > > numbers, etc., if we are using these.
> > > >
> > > > One way to approach this is for each one of us
> > to
> > > try
> > > > to write down some documentation conventions
> > that
> > > we
> > > > are following when writing the documentation.
> 
=== message truncated ===



 
____________________________________________________________________________________
Sponsored Link

Mortgage rates near 39yr lows. 
$310k for $999/mo. Calculate new payment! 
www.LowerMyBills.com/lre

Mime
View raw message