directory-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Emmanuel Lecharny" <elecha...@gmail.com>
Subject Re: Standardized Documentation Markup and Best Practices
Date Sun, 19 Nov 2006 18:30:17 GMT
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
> > > > > to search and well organized.
> > > > >
> > > > > Cheers,
> > > > > - Ole
> > > > >
> > > > >
> > > > >
> > > > >
> > > >
> > >
> >
>
> ____________________________________________________________________________________
> > > > > Sponsored Link
> > > > >
> > > > > $420k for $1,399/mo.
> > > > > Think You Pay Too Much For Your Mortgage?
> > > > > Find Out! www.LowerMyBills.com/lre
> > > > >
> > > >
> > > >
> > > >
> > > > --
> > > > Cordialement,
> > > > Emmanuel L├ęcharny
> > >
> > >
> > > --
> > > Ersin
> > >
> >
> >
> >
> >
> >
>
> ____________________________________________________________________________________
> > Sponsored Link
> >
> > Compare mortgage rates for today.
> > Get up to 5 free quotes.
> > Www2.nextag.com
> >
>
>
>
>
>
> ____________________________________________________________________________________
> Sponsored Link
>
> Compare mortgage rates for today.
> Get up to 5 free quotes.
> Www2.nextag.com
>



-- 
Cordialement,
Emmanuel L├ęcharny

Mime
View raw message