I actually think moving this to the wiki is not a bad idea... that is
what we have done for all the Geronimo docs. If needed we can create
additional spaces in Confluence to hold the pure-docs aside from the
website.
I am not really sure how many Apache projects use Word to generate
docs, I can't think of any of the top of my head (doesn't mean there
aren't any). But generally more open and accessible formats are
preferred, so that if I want to help with the docs I don't have to go
out and buy Microsoft Word/Office to do it. I suppose OpenOffice
would work as long as the format is compatible.
I have not tried recently, but in the past changes to a Word doc, even
the xml flavors often make scm change logs very difficult to grok and
comprehend what was actually changed. This can be easier with formats
like docbook, or using Confluence's change notification emails.
BTW, a Confluence space can be exported as a PDF file, so you'd get
html and PDF (plus wiki markup) versions of the docs. The only thing
is that the "root source document" would be a Confluence space, not a
single file on a file system.
* * *
I'm pro-Confluence for docs.
--jason
On Jul 7, 2009, at 6:32 PM, Bruggeman, Michael wrote:
In my opinion the best solution is to generate all of the
documentation from a root source document, such as a word document
and from that root doc. HTML and PDF formats can easily be generated.
Michael
-----Original Message-----
From: Baram, Eliezer
Sent: Tuesday, July 07, 2009 2:24 PM
To: [email protected]
Subject: RE: [jira] Created: (WINK-25) The
Symphony_SDK_2.0_Features_List.pdf and its content need to refer to
Wink instead of Symphony
The thanks are to Michael Bruggeman who updated the docs.
I think the best solution would be if we have both, a html version
for the reasons you mentioned and also a pdf version that can be
part of the distribution zip so people who download Wink would be
able to work with and print. It would also help us bundle the
documentation per a specific version, so people with older version
then the latest (once we have older versions :)) will be able to
easily find the documentation of the version they have.
I do not want to manage the two instances of the same document (wiki
and pdf) so the best solution IMO would be if we could generate one
instance out of the other. Wiki provides an option to generate a
pdf format out of it, but I'm not sure if it gives the full
capabilities we would like to have in the pdf like cross references,
index, etc and I'm afraid we would need to keep all the
documentation in one wiki page in order to be able to generate pdf
out of it, a page that can grow to several hundreds of "pages".
I do not have experience in managing documents in several formats
and I'll be happy to hear good practices.
--Eli
From: Nicholas L Gallardo [mailto:[email protected]]
Sent: Monday, July 06, 2009 7:11 PM
To: [email protected]
Subject: RE: [jira] Created: (WINK-25) The
Symphony_SDK_2.0_Features_List.pdf and its content need to refer to
Wink instead of Symphony
Thanks for updating the doc Eli. There's still some HP branding on
the first page that we should probably change to Apache at some point.
So, I'm just going to throw this out there. What would you guys
think about taking the content in the PDF and getting it on the
wiki? I'm not saying that it has to be done immediately, or that you
in particular should do it. But want to see what others think about
that.
Here's my reasoning... The content in the document in excellent, but
as a user my primary problem solving tool is Google. When I go to
search for information related to Wink that probably exists in that
doc, I won't find it. The harder it is to find the necessary
information, the less likely it is for people to a) help themselves
in terms of development and debugging and b) it's less likely for
people to use the project when they can't find what's supported
easily.
Just a thought...
-Nick
Nicholas Gallardo
WebSphere - REST & WebServices Development
[email protected]
Phone: 512-286-6258
Building: 903 / 5G-016
[cid:[email protected]]"Baram, Eliezer" <[email protected]
>
"Baram, Eliezer" <[email protected]>
07/05/2009 06:58 AM
Please respond to
[email protected]
To
"[email protected]" <[email protected]>
cc
Subject
RE: [jira] Created: (WINK-25) The Symphony_SDK_2.0_Features_List.pdf
and its content need to refer to Wink instead of Symphony
Hi Michael
All the "symphony" references including the those who are part of
parameter or a property name should be changed to wink.
For those who are parameter or a property we should also do code
changes, part of them where already been changed (WINK-14).
Regards,
Eli
-----Original Message-----
From: Bruggeman, Michael
Sent: Sunday, July 05, 2009 2:36 PM
To: [email protected]
Subject: RE: [jira] Created: (WINK-25) The
Symphony_SDK_2.0_Features_List.pdf and its content need to refer to
Wink instead of Symphony
Hi Eli,
What about all of these instances of the "Symphony word used in the
code.
symphony.serviceDocumentCssPath
-----Original Message-----
From: Eli Baram (JIRA) [mailto:[email protected]]
Sent: Wednesday, July 01, 2009 11:49 AM
To: [email protected]
Subject: [jira] Created: (WINK-25) The
Symphony_SDK_2.0_Features_List.pdf and its content need to refer to
Wink instead of Symphony
The Symphony_SDK_2.0_Features_List.pdf and its content need to refer
to Wink instead of Symphony
------------------------------------------------------------------------------------------------
Key: WINK-25
URL: https://issues.apache.org/jira/browse/WINK-25
Project: Wink
Issue Type: Task
Components: Documentation
Affects Versions: 0.1
Reporter: Eli Baram
--
This message is automatically generated by JIRA.
-
You can reply to this email to add a comment to the issue online.
