Thanks for chiming in folks. Glad to hear others are interested in moving that way as well.
I agree with Jason's point below that the ability to edit the docs should be generally accessible. Jason, can you think of any examples of PDFs that have been generated from cwiki content? I'd be curious to see how much it resembles the wiki itself. Eli made good points earlier too about not wanting to have a single page that became the doc. It needs to be a well-organized tree that can then have a PDF generated from there. Don't know if that's possible though. Another point to consider. For the online docs, it would be nice to keep them versioned under link that correspond to the release (separate docs for 0.1, 0.2, 1.0, etc.) -Nick Nicholas Gallardo WebSphere - REST & WebServices Development [email protected] Phone: 512-286-6258 Building: 903 / 5G-016 Jason Dillon <[email protected] om> To Sent by: Jason [email protected] Dillon cc <jason.dil...@gma il.com> Subject Re: [jira] Created: (WINK-25) The Symphony_SDK_2.0_Features_List.pdf 07/07/2009 06:44 and its content need to refer to AM Wink instead of Symphony Please respond to wink-...@incubato r.apache.org 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. >
