You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@wink.apache.org by Bryant Luk <br...@gmail.com> on 2009/06/11 16:22:31 UTC

Documentation formats?

Hi all,

Thinking about the runtime comparison, there's a mention of
documentation for the runtime itself, user guide, and samples.  Is
there any particular documentation format that everyone likes?  To be
honest, I don't have much experience with that many documentation
markup languages.  I'm guessing that we need the documentation in a
format that's easily transformable to whatever final output formats
are required (PDF, Word, HTML,...?).  Or is the project documentation
going to be only in the Maven site formats?
-- 

- Bryant Luk

RE: Documentation formats?

Posted by "Snitkovsky, Martin" <ma...@hp.com>.
<...think we should concentrate on the site/wiki first and we can always
copy/paste that later>

+1

-----Original Message-----
From: Bryant Luk [mailto:bryant.luk@gmail.com] 
Sent: Tuesday, June 16, 2009 10:40 PM
To: wink-dev@incubator.apache.org
Subject: Re: Documentation formats?

I think this sounds good.  I was looking into DocBook / Dita to see if
we could use that so we could just generate PDFs/Word docs/etc. but I
think we should concentrate on the site/wiki first and we can always
copy/paste that later.

On Sun, Jun 14, 2009 at 10:39 AM, Snitkovsky,
Martin<ma...@hp.com> wrote:
> This is an interesting point.
>
> IMO, all information that is required to get familiar with the project (e.g. "getting started", "simple examples", "fealties list", "change log", FAQs ) can be documented in Maven apt format (eclipse has an apt plug-in that generates final HTML files for debugging purposes).
>
> "User Guide" document should be provided in either PDF or Word formats, since PDF/Word provide advanced features like "cross ref", "document map view", "indexes" etc.. making such documents much more readable then in HTML, for example.
>
> Thoughts?
>
> --Martin
>
>
> -----Original Message-----
> From: Bryant Luk [mailto:bryant.luk@gmail.com]
> Sent: Thursday, June 11, 2009 5:23 PM
> To: wink-dev@incubator.apache.org
> Subject: Documentation formats?
>
> Hi all,
>
> Thinking about the runtime comparison, there's a mention of
> documentation for the runtime itself, user guide, and samples.  Is
> there any particular documentation format that everyone likes?  To be
> honest, I don't have much experience with that many documentation
> markup languages.  I'm guessing that we need the documentation in a
> format that's easily transformable to whatever final output formats
> are required (PDF, Word, HTML,...?).  Or is the project documentation
> going to be only in the Maven site formats?
> --
>
> - Bryant Luk
>



-- 

- Bryant Luk

Re: Documentation formats?

Posted by Bryant Luk <br...@gmail.com>.
I think this sounds good.  I was looking into DocBook / Dita to see if
we could use that so we could just generate PDFs/Word docs/etc. but I
think we should concentrate on the site/wiki first and we can always
copy/paste that later.

On Sun, Jun 14, 2009 at 10:39 AM, Snitkovsky,
Martin<ma...@hp.com> wrote:
> This is an interesting point.
>
> IMO, all information that is required to get familiar with the project (e.g. "getting started", "simple examples", "fealties list", "change log", FAQs ) can be documented in Maven apt format (eclipse has an apt plug-in that generates final HTML files for debugging purposes).
>
> "User Guide" document should be provided in either PDF or Word formats, since PDF/Word provide advanced features like "cross ref", "document map view", "indexes" etc.. making such documents much more readable then in HTML, for example.
>
> Thoughts?
>
> --Martin
>
>
> -----Original Message-----
> From: Bryant Luk [mailto:bryant.luk@gmail.com]
> Sent: Thursday, June 11, 2009 5:23 PM
> To: wink-dev@incubator.apache.org
> Subject: Documentation formats?
>
> Hi all,
>
> Thinking about the runtime comparison, there's a mention of
> documentation for the runtime itself, user guide, and samples.  Is
> there any particular documentation format that everyone likes?  To be
> honest, I don't have much experience with that many documentation
> markup languages.  I'm guessing that we need the documentation in a
> format that's easily transformable to whatever final output formats
> are required (PDF, Word, HTML,...?).  Or is the project documentation
> going to be only in the Maven site formats?
> --
>
> - Bryant Luk
>



-- 

- Bryant Luk

RE: Documentation formats?

Posted by "Snitkovsky, Martin" <ma...@hp.com>.
This is an interesting point. 

IMO, all information that is required to get familiar with the project (e.g. "getting started", "simple examples", "fealties list", "change log", FAQs ) can be documented in Maven apt format (eclipse has an apt plug-in that generates final HTML files for debugging purposes). 

"User Guide" document should be provided in either PDF or Word formats, since PDF/Word provide advanced features like "cross ref", "document map view", "indexes" etc.. making such documents much more readable then in HTML, for example.

Thoughts?

--Martin 
 

-----Original Message-----
From: Bryant Luk [mailto:bryant.luk@gmail.com] 
Sent: Thursday, June 11, 2009 5:23 PM
To: wink-dev@incubator.apache.org
Subject: Documentation formats?

Hi all,

Thinking about the runtime comparison, there's a mention of
documentation for the runtime itself, user guide, and samples.  Is
there any particular documentation format that everyone likes?  To be
honest, I don't have much experience with that many documentation
markup languages.  I'm guessing that we need the documentation in a
format that's easily transformable to whatever final output formats
are required (PDF, Word, HTML,...?).  Or is the project documentation
going to be only in the Maven site formats?
-- 

- Bryant Luk