You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@directory.apache.org by Ole Ersoy <ol...@yahoo.com> on 2006/11/19 04:48:30 UTC
Standardized Documentation Markup and Best Practices
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
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
Yeah - Whoa!
Nice work.
OK - Since no-one officially told me to "Shaaaattt
Up!!" yet (I think I'm getting close though :-) ),
I'm going to bug everyone to look at this link.
http://cwiki.apache.org/confluence/display/DIRxSRVx11/Cookbook+Documentation+Template
It's just a sample cookbook like template with
instructions for how to use it.
I'll be using this to document the JPackage RPM
Plugin, and just about everything else once the Plugin
is outta hea.
At the bottom of the template in the
Related Material
section
there's a link to my first "Cookbook" page on creating
a JPackage RPM project using the JPacage RPM
Archetype.
Cheers,
- Ole
--- Alex Karasulu <ao...@bellsouth.net> wrote:
> Ersin Er wrote:
> > On 11/20/06, Alex Karasulu <ao...@bellsouth.net>
> wrote:
> >> Stefan Zoerner wrote:
> >> > Ole Ersoy 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?
> >> >>
> >> >
> >> > As a quick solution, I like the way Trustin
> does this with MINA. Ersin
> >> > has already elaborated how it works. Of course
> it will not be
> >> sufficient
> >> > if we also want to have the documentation in
> other formats in the
> >> > future. But currently the focus is content, not
> format (as Emmanuel has
> >> > explained).
> >> >
> >>
> >> Yep I agree with both points regarding focus on
> content and the use of
> >> the same URL rewriting that MINA has utilized.
> >>
> >> Ersin since you're involved with the infra folks
> can you look into what
> >> it would take to do the same with the directory
> site?
> >
> > We already did it. It's really simple.
> >
> > http://directory.apache.org/TEST/
> >
>
> Nice!!!
>
> Let's get the whole site doing this whoa!!!
> Alex
>
____________________________________________________________________________________
Sponsored Link
Mortgage rates near 39yr lows.
$310k for $999/mo. Calculate new payment!
www.LowerMyBills.com/lre
Re: Standardized Documentation Markup and Best Practices
Posted by Alex Karasulu <ao...@bellsouth.net>.
Ersin Er wrote:
> On 11/20/06, Alex Karasulu <ao...@bellsouth.net> wrote:
>> Stefan Zoerner wrote:
>> > Ole Ersoy 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?
>> >>
>> >
>> > As a quick solution, I like the way Trustin does this with MINA. Ersin
>> > has already elaborated how it works. Of course it will not be
>> sufficient
>> > if we also want to have the documentation in other formats in the
>> > future. But currently the focus is content, not format (as Emmanuel has
>> > explained).
>> >
>>
>> Yep I agree with both points regarding focus on content and the use of
>> the same URL rewriting that MINA has utilized.
>>
>> Ersin since you're involved with the infra folks can you look into what
>> it would take to do the same with the directory site?
>
> We already did it. It's really simple.
>
> http://directory.apache.org/TEST/
>
Nice!!!
Let's get the whole site doing this whoa!!!
Alex
Re: Standardized Documentation Markup and Best Practices
Posted by Ersin Er <er...@gmail.com>.
On 11/20/06, Alex Karasulu <ao...@bellsouth.net> wrote:
> Stefan Zoerner wrote:
> > Ole Ersoy 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?
> >>
> >
> > As a quick solution, I like the way Trustin does this with MINA. Ersin
> > has already elaborated how it works. Of course it will not be sufficient
> > if we also want to have the documentation in other formats in the
> > future. But currently the focus is content, not format (as Emmanuel has
> > explained).
> >
>
> Yep I agree with both points regarding focus on content and the use of
> the same URL rewriting that MINA has utilized.
>
> Ersin since you're involved with the infra folks can you look into what
> it would take to do the same with the directory site?
We already did it. It's really simple.
http://directory.apache.org/TEST/
> Thanks,
> Alex
>
--
Ersin
Re: Standardized Documentation Markup and Best Practices
Posted by Alex Karasulu <ao...@bellsouth.net>.
Stefan Zoerner wrote:
> Ole Ersoy 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?
>>
>
> As a quick solution, I like the way Trustin does this with MINA. Ersin
> has already elaborated how it works. Of course it will not be sufficient
> if we also want to have the documentation in other formats in the
> future. But currently the focus is content, not format (as Emmanuel has
> explained).
>
Yep I agree with both points regarding focus on content and the use of
the same URL rewriting that MINA has utilized.
Ersin since you're involved with the infra folks can you look into what
it would take to do the same with the directory site?
Thanks,
Alex
Re: Standardized Documentation Markup and Best Practices
Posted by Stefan Zoerner <sz...@apache.org>.
Ole Ersoy 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?
>
As a quick solution, I like the way Trustin does this with MINA. Ersin
has already elaborated how it works. Of course it will not be sufficient
if we also want to have the documentation in other formats in the
future. But currently the focus is content, not format (as Emmanuel has
explained).
Greetings, Stefan
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
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 <ol...@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 <ol...@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 <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
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 <ol...@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 <el...@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 <ol...@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 <ol...@yahoo.com> wrote:
> > >
> > > > OK cool - Sounds like we're on top of it!
> > > >
> > > > --- Ersin Er <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
> > > > <el...@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
> <ol...@yahoo.com>
>
=== message truncated ===
____________________________________________________________________________________
Sponsored Link
Mortgage rates near 39yr lows.
$310k for $999/mo. Calculate new payment!
www.LowerMyBills.com/lre
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
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 <el...@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 <ol...@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 <ol...@yahoo.com> wrote:
> >
> > > OK cool - Sounds like we're on top of it!
> > >
> > > --- Ersin Er <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
> > > <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Emmanuel Lecharny <el...@gmail.com>.
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 <ol...@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 <ol...@yahoo.com> wrote:
>
> > OK cool - Sounds like we're on top of it!
> >
> > --- Ersin Er <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
> > <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
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 <ol...@yahoo.com> wrote:
> OK cool - Sounds like we're on top of it!
>
> --- Ersin Er <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
> <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Ole Ersoy <ol...@yahoo.com>.
OK cool - Sounds like we're on top of it!
--- Ersin Er <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 <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Ersin Er <er...@gmail.com>.
As we are good parser writers we can convert Confluence wiki format to
anything we like :-)
On 11/19/06, Emmanuel Lecharny <el...@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 <ol...@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
Re: Standardized Documentation Markup and Best Practices
Posted by Emmanuel Lecharny <el...@gmail.com>.
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 <ol...@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