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 18:46:12 GMT
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.
> >
> > If we all use a template page for this we could
> find a
> > common intersection that everyone agrees upon.
> >
> > Another thing to consider is having standardized
> > templates for writing on specific topics.
> >
> > Like a cookbook type template with standardized
> > headings.
> >
> > This makes it really easy for someone to writeup a
> > topic really quick without really having to thing
> > about markup or what the markup semantics should
> be.
> >
> > wdyt?
> >
> >
> >
> >
> > --- Ole Ersoy <ole_ersoy@yahoo.com> wrote:
> >
> > > OK cool - Sounds like we're on top of it!
> > >
> > > --- Ersin Er <ersin.er@gmail.com> wrote:
> > >
> > > > As we are good parser writers we can convert
> > > > Confluence wiki format to
> > > > anything we like :-)
> > > >
> > > > On 11/19/06, Emmanuel Lecharny
> > > <elecharny@gmail.com>
> > > > wrote:
> > > > > Hi Ole,
> > > > >
> > > > > FYI, mozilla wiki is dead for us. We now use
> > > > cwiki, which is confluence, so
> > > > > I think we will stick to confluence wiki
> markup
> > > ;)
> > > > >
> > > > > Emmanuel
> > > > >
> > > > >
> > > > > On 11/19/06, Ole Ersoy <ole_ersoy@yahoo.com>
> > > > wrote:
> > > > > > Hey Guys,
> > > > > >
> > > > > > I think one of the goals for our
> documentation
> > > > > > should be to separate the formatting and
> the
> > > > content,
> > > > > > so that content can easily be reformatted
> /
> > > > sliced
> > > > > > diced...
> > > > > > thus we maximize our content management
> > > > flexibility.
> > > > > >
> > > > > > I thought this could be accomplished by
> just
> > > > using
> > > > > > wiki markup as the markup standard.
> > > > > >
> > > > > > So I started reading up on wiki markup. 
> It
> > > > turns out
> > > > > > there's different wiki markup conventions.
> > > > > >
> > > > > > For instance Confluence uses
> > > > > >
> > > > > > h1.
> > > > > > h2.
> > > > > > etc.
> > > > > >
> > > > > > for sections.
> > > > > >
> > > > > > The mozilla wiki and I think most other
> wikis
> > > > use
> > > > > >
> > > > > > ==Section1==
> > > > > > ===SubSection1===
> > > > > >
> > > > > > For sections.
> > > > > >
> > > > > >
> > > > > >
> > > > > > So say down the road we want to turn our
> > > > documentation
> > > > > > into XML for whatever reason.
> > > > > >
> > > > > > Do we need to write a special confluence
> wiki
> > > > markup
> > > > > > parser now?
> > > > > >
> > > > > > Right now is a good time to put some
> thought
> > > > into how
> > > > > > we markup our documentation, before we
> have a
> > > > mountain
> > > > > > of it :-)
> > > > > >
> > > > > > Does anyone know of an easy to use
> "Universal"
> > > > markup
> > > > > > standard?
> > > > > >
> > > > > > I think we are trying to get this on
> > > confluence,
> > > > so
> > > > > > ideally it would be easy to integrate the
> two.
> > > > > >
> > > > > > Can we upload regular html pages into
> > > confluence
> > > > for
> > > > > > display?
> > > > > >
> > > > > > If so we can use whatever markup we please
> and
> > > > just
> > > > > > upload the pages.
> > > > > >
> > > > > > Personally I'd like to see all
> documentation
> > > in
> > > > > > something like the Eclipse Help System,
> which
> > > is
> > > > easy
> 
=== message truncated ===



 
____________________________________________________________________________________
Sponsored Link

Online degrees - find the right program to advance your career.
Www.nextag.com

Mime
View raw message