Re: The Apache Way (Re: describe Forrest in 50 words)
David Crossley wrote: Ross Gardler wrote: Since we have a number of new developers arriving perhaps those new to the Apache Way would like to read: Consensus Gauging through Voting: http://www.apache.org/foundation/voting.html Which states in the introduction: There are essentially three types of vote: 1. Code modifications, 2. Package releases 3. Procedural (note there is nothing there about decision making) You may also be interested in this blog post and those linked from it: http://blog.generationjava.com/roller/page/bayard/20050319#apache_meritocracy_consensus_and_despotism http://www.anyware-tech.com/blogs/sylvain/archives/000172.html and http://www.jroller.com/page/rgardler/20050324#effective_decision_making_in_community (which all say much the same thing but all come from slightly different angles) --- I wounder if we should put some/all of these links into one of our mail templates for inviting/accepting a new committer? It would be better to distill those comments into the top-level documents at www.apache.org/dev/ But yeah, linking to them is next best. I like yours the most. Someone should press-gang you into writing documents for Forrest. :-)) The blog entry is Creative Commons licensed, I hereby give permission for someone to copy it into any relevant Apache document and relicense it accordingly. Ross
Re: The Apache Way (Re: describe Forrest in 50 words)
Ross Gardler wrote: > > Since we have a number of new developers arriving perhaps those new to > the Apache Way would like to read: > > Consensus Gauging through Voting: > http://www.apache.org/foundation/voting.html > > Which states in the introduction: > > There are essentially three types of vote: > >1. Code modifications, >2. Package releases >3. Procedural > > (note there is nothing there about decision making) > > You may also be interested in this blog post and those linked from it: > > http://blog.generationjava.com/roller/page/bayard/20050319#apache_meritocracy_consensus_and_despotism > > http://www.anyware-tech.com/blogs/sylvain/archives/000172.html > > and > > http://www.jroller.com/page/rgardler/20050324#effective_decision_making_in_community > > (which all say much the same thing but all come from slightly different > angles) > > --- > > I wounder if we should put some/all of these links into one of our mail > templates for inviting/accepting a new committer? It would be better to distill those comments into the top-level documents at www.apache.org/dev/ But yeah, linking to them is next best. I like yours the most. Someone should press-gang you into writing documents for Forrest. These are the other documents that we refer new developers to: http://www.apache.org/foundation/how-it-works.html http://www.apache.org/dev/ http://forrest.apache.org/guidelines.html --David
Re: describe Forrest in 50 words
Ross Gardler wrote: RG> I read that the *output* strictly separates content from presentation, RG> thereby implying that the *input* does not. Whilst some input formats RG> blur this distinction (like OOo and MS Office for example) I'm not sure RG> we can claim to take a horrible mess of an input document and create a RG> nicely separated output. yeah, but fixing that impression will confuse things even more. Saying that 'Forrest for *input* strictly separates content from presentation' is not true either. Problem here is that separate can have two different meanings: a) to keep apart b) to take apart What it should say is that 'Forrest expects and works best with input that strictly separates content from presentation', but that is way beyond our 50 words. So I' suggest to stick with the proposed version in this respect. Although, while I'm at it ... ** Apache Forrest is a publishing framework that transforms input from various sources into a unified presentation in one or more output formats. Its modular and extensible plugin-architecture is based on Apache Cocoon and several Web standards and strictly separates presentation from content. Forrest can generate static documents, run on an application server or be deployed by an automated publishing application. ** main suggestion is to replace document collection with presentation because that seems to better include menues, tabs and tocs whereas document collection reminds me a bit of a file system view. And I was so determined to keep out of this to get some work done :-) -- Ferdinand Soethe
Re: describe Forrest in 50 words
Ross Gardler wrote: David Crossley wrote: Johannes Schaefer wrote: Now that David gave the last version, I'll try to comment ... also dared a look into the archive. HERE'S MY TRY: Apache Forrest is a publishing framework that accepts various input sources and transforms them into a unified document collection strictly separating content and presentation. It is standards-based, employing Apache Cocoon and a plugin architecture which makes it modular and extensible. Forrest can be used as a dynamic application, to generate a static result or completely automated. ... Brilliant work. I would only tweak the last sentence to have better words than "static result" and the "completely automated" seems to lose some of the meaning. I agree (sorry little time at present so I can't make a suggestion). What do others think? I reckon that we are getting close. Minor point: I read that the *output* strictly separates content from presentation, thereby implying that the *input* does not. Whilst some input formats blur this distinction (like OOo and MS Office for example) I'm not sure we can claim to take a horrible mess of an input document and create a nicely separated output. fast as well: I meant the separation of concerns for the *framework*, not only the *output*. Maybe some commas would help (relative clause from "that" to "collection")? Or like this: >>>Apache Forrest is a publishing framework strictly >>>separating content and presentation. It accepts >>> various input sources and transforms them into a unified >>> document collection. This is where my English fails :-( js Ross -- User Interface Design GmbH * Teinacher Str. 38 * D-71634 Ludwigsburg Fon +49 (0)7141 377 000 * Fax +49 (0)7141 377 00-99 Geschäftsstelle: User Interface Design GmbH * Lehrer-Götz-Weg 11 * D-81825 München www.uidesign.de Buch "User Interface Tuning" von Joachim Machate & Michael Burmester www.user-interface-tuning.de
Re: describe Forrest in 50 words
David Crossley wrote: Johannes Schaefer wrote: Now that David gave the last version, I'll try to comment ... also dared a look into the archive. HERE'S MY TRY: Apache Forrest is a publishing framework that accepts various input sources and transforms them into a unified document collection strictly separating content and presentation. It is standards-based, employing Apache Cocoon and a plugin architecture which makes it modular and extensible. Forrest can be used as a dynamic application, to generate a static result or completely automated. ... Brilliant work. I would only tweak the last sentence to have better words than "static result" and the "completely automated" seems to lose some of the meaning. I agree (sorry little time at present so I can't make a suggestion). What do others think? I reckon that we are getting close. Minor point: I read that the *output* strictly separates content from presentation, thereby implying that the *input* does not. Whilst some input formats blur this distinction (like OOo and MS Office for example) I'm not sure we can claim to take a horrible mess of an input document and create a nicely separated output. Ross
The Apache Way (Re: describe Forrest in 50 words)
David Crossley wrote: Ferdinand Soethe wrote: David Crossley wrote: DC> I am saying that decisions should be reached DC> through consensus rather than competition. DC> In this case, it would be better to evolve the DC> Forrest description until it is suitable. I can see what David is saying. Though it wouldn't hurt if more people voiced an opinion and stated which text we should continue refining. Or - like David - proposed another version to discuss. Since we have a number of new developers arriving perhaps those new to the Apache Way would like to read: Consensus Gauging through Voting: http://www.apache.org/foundation/voting.html Which states in the introduction: There are essentially three types of vote: 1. Code modifications, 2. Package releases 3. Procedural (note there is nothing there about decision making) You may also be interested in this blog post and those linked from it: http://blog.generationjava.com/roller/page/bayard/20050319#apache_meritocracy_consensus_and_despotism http://www.anyware-tech.com/blogs/sylvain/archives/000172.html and http://www.jroller.com/page/rgardler/20050324#effective_decision_making_in_community (which all say much the same thing but all come from slightly different angles) --- I wounder if we should put some/all of these links into one of our mail templates for inviting/accepting a new committer? Ross
Re: describe Forrest in 50 words
David Crossley wrote: ... That is a very good point. Discussion should happen during the proposal phase to arrive at a good solution. If a vote is considered to be needed, then that is called at the end to be sure that people are happy with the direction. Yup. As an important Apache member told me, votes tend to polarize. Since Apache is about consensus, calling a vote too early does not help. In a 'perfect' Apache project, votes are necessary only for releasing and checking consensus on important decisions. -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: describe Forrest in 50 words
Johannes Schaefer wrote: > Now that David gave the last version, > I'll try to comment ... also dared a look > into the archive. > > HERE'S MY TRY: > Apache Forrest is a publishing framework that accepts > various input sources and transforms them into a unified > document collection strictly separating content and > presentation. > It is standards-based, employing Apache Cocoon and > a plugin architecture which makes it modular and > extensible. > Forrest can be used as a dynamic application, > to generate a static result or completely automated. >WORDCOUNT=58 > > > Comments: > * Easier wording. For me as a non-native speaker the prev. > versions were harder to understand. Shorter sentences. > (Please correct any errors in my English!) I don't see any such. > * Put the main thing up-front: what forrest does. Then > something about the architecture, then the options. Good idea. > * I'm not very happy with the last sentence. Me either. I prefer the previous version of that sentence. > * For discussion: "publishing" instead of "documentation" > framework. This includes web publishing, classic > documentation (read books, articles), online help etc. Does publishing cover intranet documentation systems, say inside a factory? I would think so. > * We might want to spend an extra word, saying "extremely > modular and extensible". Not necessary. > What do you think? Brilliant work. I would only tweak the last sentence to have better words than "static result" and the "completely automated" seems to lose some of the meaning. What do others think? I reckon that we are getting close. Don't get too hung up on the 50 word thing. Even 70 would be okay, though the more concise the better. And hey, i love your style of commenting by providing your reasoning. --David
Re: describe Forrest in 50 words
Ferdinand Soethe wrote: > David Crossley wrote: > > DC> I am saying that decisions should be reached > DC> through consensus rather than competition. > > DC> In this case, it would be better to evolve the > DC> Forrest description until it is suitable. > > I can see what David is saying. Though it wouldn't hurt if more people > voiced an opinion and stated which text we should continue refining. > Or - like David - proposed another version to discuss. It it hard to get opinions flowing. One aspect of the Apache Way is for developers to just get in and do it. Those who care, and find the time, will pitch in to help. Others will just let those who are doing it get on with the job, and will just speak up when they see a key element going astray. > Just calling a vote might end that debate and leave us short of an > optimal solution (which is more important than 50 word suggest). That is a very good point. Discussion should happen during the proposal phase to arrive at a good solution. If a vote is considered to be needed, then that is called at the end to be sure that people are happy with the direction. If a vote is called too early, then either it stifles the solution or just more discussion happens, mixed up with the actual vote and the proposal changes under our feet. Messy. In the end, we want to just get on and produce our work as efficiently as possible, with as little beauracracy as possible. --David
Re: describe Forrest in 50 words
Now that David gave the last version, I'll try to comment ... also dared a look into the archive. HERE'S MY TRY: Apache Forrest is a publishing framework that accepts various input sources and transforms them into a unified document collection strictly separating content and presentation. It is standards-based, employing Apache Cocoon and a plugin architecture which makes it modular and extensible. Forrest can be used as a dynamic application, to generate a static result or completely automated. WORDCOUNT=58 Comments: * Easier wording. For me as a non-native speaker the prev. versions were harder to understand. Shorter sentences. (Please correct any errors in my English!) * Put the main thing up-front: what forrest does. Then something about the architecture, then the options. * I'm not very happy with the last sentence. * For discussion: "publishing" instead of "documentation" framework. This includes web publishing, classic documentation (read books, articles), online help etc. * We might want to spend an extra word, saying "extremely modular and extensible". What do you think? Johannes David Crossley wrote: Ferdinand Soethe wrote: Ross Gardler wrote: RG> I'd say stick with what we had I agree. No point in having a lengthy discussion. To a large extent it depends on the perspective you have and the background you come from. So if you feel happier with it, just ignore my proposal and stick with the previous text. Here is the new version trying to take some of Ferdinand's words into account. If no-one has anything more to add or change, then i will go ahead and use this. Apache Forrest is a standards-based documentation framework using a plugin architecture to transform and aggregate various input sources into various output formats. It is modular and extensible, based on Apache Cocoon, to emphasise the strict separation of presentation and content. This creates a unified document collection that can be used as a dynamic application, or generated at the command-line, or generated and deployed with an automated publishing application. --David -- User Interface Design GmbH * Teinacher Str. 38 * D-71634 Ludwigsburg Fon +49 (0)7141 377 000 * Fax +49 (0)7141 377 00-99 Geschäftsstelle: User Interface Design GmbH * Lehrer-Götz-Weg 11 * D-81825 München www.uidesign.de Buch "User Interface Tuning" von Joachim Machate & Michael Burmester www.user-interface-tuning.de
Re: describe Forrest in 50 words
David Crossley wrote: DC> I am saying that decisions should be reached DC> through consensus rather than competition. DC> In this case, it would be better to evolve the DC> Forrest description until it is suitable. I can see what David is saying. Though it wouldn't hurt if more people voiced an opinion and stated which text we should continue refining. Or - like David - proposed another version to discuss. Just calling a vote might end that debate and leave us short of an optimal solution (which is more important than 50 word suggest). -- Ferdinand Soethe
Re: describe Forrest in 50 words
Thorsten Scherler wrote: > David Crossley wrote: > > The Apache voting system is not used to settle competing views. > > It is intended to ensure that people are happy with the > > proposed course. If a vote fails then we go back to the > > proposal stage and come up with something different. > > You mean we cannot decide between two proposals? That is new because I > have seen it a lot on other list. > > I was thing about: > - alternative A > - alternative B > > ...but if you say that is not possible,... I am saying that decisions should be reached through consensus rather than competition. Some projects use voting too often, rather than working through the issues. In this case, it would be better to evolve the Forrest description until it is suitable. In extreme cases, the "aternatives" type of voting might make sense. However, most of the ones that i have seen become quite confused. It is easy to reach a stalemate with for example only three votes for each alternative, or even a -1 on each side which stops both proposals. The Apache voting system is geared towards assessing one proposal at a time. However, we really should strive to do things without voting, i.e. "just do it" or if it needs discussion, then discuss the proposals until the decision is obvious. --David
Re: describe Forrest in 50 words
David Crossley wrote: ... The Apache voting system is not used to settle competing views. It is intended to ensure that people are happy with the proposed course. How true! +1 :-) -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: describe Forrest in 50 words
Ferdinand Soethe wrote: > Ross Gardler wrote: > > RG> I'd say stick with what we had > > I agree. No point in having a lengthy discussion. To a large extent it > depends on the perspective you have and the background you come from. > > So if you feel happier with it, just ignore my proposal and > stick with the previous text. Here is the new version trying to take some of Ferdinand's words into account. If no-one has anything more to add or change, then i will go ahead and use this. Apache Forrest is a standards-based documentation framework using a plugin architecture to transform and aggregate various input sources into various output formats. It is modular and extensible, based on Apache Cocoon, to emphasise the strict separation of presentation and content. This creates a unified document collection that can be used as a dynamic application, or generated at the command-line, or generated and deployed with an automated publishing application. --David
Re: describe Forrest in 50 words
On Wed, 2005-04-27 at 21:51 +1000, David Crossley wrote: > The Apache voting system is not used to settle competing views. > It is intended to ensure that people are happy with the > proposed course. If a vote fails then we go back to the > proposal stage and come up with something different. You mean we cannot decide between two proposals? That is new because I have seen it a lot on other list. I was thing about: - alternative A - alternative B ...but if you say that is not possible,... salu2 -- thorsten "Together we stand, divided we fall!" Hey you (Pink Floyd)
Re: describe Forrest in 50 words
Thorsten Scherler wrote: > Ferdinand Soethe wrote: > > David Crossley wrote: > > > > DC> We can enhance the original. Ferdinand, i don't mean > > DC> to dismiss any of your contribution. > > > > OK, that's fine by me. Just go ahead and change what bugged you > > about it. > > > > On the other hand: A lot of people put their mind on improving the > > previous text, so may be it was not such a great idea for me to come > > up with something totally different. No, that was fine. It is good that people contribute their views at any time. > > It might help to hear some more voices on this? > > To be honest I can understand your SSP approach and I can see why it > seems to be limiting, but I would prefer when we have a vote with the > different proposals and then see which one wins. The Apache voting system is not used to settle competing views. It is intended to ensure that people are happy with the proposed course. If a vote fails then we go back to the proposal stage and come up with something different. --David
Re: describe Forrest in 50 words
On Wed, 2005-04-27 at 11:25 +0200, Johannes Schaefer wrote: > Thorsten Scherler wrote: > > On Wed, 2005-04-27 at 10:25 +0200, Ferdinand Soethe wrote: > > > >>David Crossley wrote: > >> > >>DC> We can enhance the original. Ferdinand, i don't mean > >>DC> to dismiss any of your contribution. > >> > >>OK, that's fine by me. Just go ahead and change what bugged you > >>about it. > >> > >>On the other hand: A lot of people put their mind on improving the > >>previous text, so may be it was not such a great idea for me to come > >>up with something totally different. > >> > >>It might help to hear some more voices on this? > > Would like to comment, but I'm not sure if I'll find > the time to read the thread :-( > > > > > To be honest I can understand your SSP approach and I can see why it > > seems to be limiting, but I would prefer when we have a vote with the > > different proposals and then see which one wins. > > > > ...I could not find a translation for: > > "Worte sind nur Schall und Rauch" ;-) > > How about (pretty free translation, though) > >- verba volant, scripta manent - > (discussions get forgotten, just code remains) > > Thanks Nicola! > :) Doh. lol. Nice one josch, (...and congrats to your first commit). ;-) salu2 > Here are some other close hits >http://makeashorterlink.com/?D23A228FA > > Johannes > > > > > > salu2 > > -- thorsten "Together we stand, divided we fall!" Hey you (Pink Floyd)
Re: describe Forrest in 50 words
Thorsten Scherler wrote: On Wed, 2005-04-27 at 10:25 +0200, Ferdinand Soethe wrote: David Crossley wrote: DC> We can enhance the original. Ferdinand, i don't mean DC> to dismiss any of your contribution. OK, that's fine by me. Just go ahead and change what bugged you about it. On the other hand: A lot of people put their mind on improving the previous text, so may be it was not such a great idea for me to come up with something totally different. It might help to hear some more voices on this? Would like to comment, but I'm not sure if I'll find the time to read the thread :-( To be honest I can understand your SSP approach and I can see why it seems to be limiting, but I would prefer when we have a vote with the different proposals and then see which one wins. ...I could not find a translation for: "Worte sind nur Schall und Rauch" ;-) How about (pretty free translation, though) - verba volant, scripta manent - (discussions get forgotten, just code remains) Thanks Nicola! Here are some other close hits http://makeashorterlink.com/?D23A228FA Johannes salu2 -- User Interface Design GmbH * Teinacher Str. 38 * D-71634 Ludwigsburg Fon +49 (0)7141 377 000 * Fax +49 (0)7141 377 00-99 Geschäftsstelle: User Interface Design GmbH * Lehrer-Götz-Weg 11 * D-81825 München www.uidesign.de Buch "User Interface Tuning" von Joachim Machate & Michael Burmester www.user-interface-tuning.de
Re: describe Forrest in 50 words
On Wed, 2005-04-27 at 10:25 +0200, Ferdinand Soethe wrote: > David Crossley wrote: > > DC> We can enhance the original. Ferdinand, i don't mean > DC> to dismiss any of your contribution. > > OK, that's fine by me. Just go ahead and change what bugged you > about it. > > On the other hand: A lot of people put their mind on improving the > previous text, so may be it was not such a great idea for me to come > up with something totally different. > > It might help to hear some more voices on this? > To be honest I can understand your SSP approach and I can see why it seems to be limiting, but I would prefer when we have a vote with the different proposals and then see which one wins. ...I could not find a translation for: "Worte sind nur Schall und Rauch" ;-) salu2 -- thorsten "Together we stand, divided we fall!" Hey you (Pink Floyd)
Re: describe Forrest in 50 words
David Crossley wrote: DC> We can enhance the original. Ferdinand, i don't mean DC> to dismiss any of your contribution. OK, that's fine by me. Just go ahead and change what bugged you about it. On the other hand: A lot of people put their mind on improving the previous text, so may be it was not such a great idea for me to come up with something totally different. It might help to hear some more voices on this? -- Ferdinand Soethe
Re: describe Forrest in 50 words
Ross Gardler wrote: > > In that case I may have liked it because of the work Ferdinand and I are > doing on the ApacheCon presentation. I'm used to his words etc. > > Stick to the original if this new one is confusing. We can enhance the original. Ferdinand, i don't mean to dismiss any of your contribution. --David
Re: describe Forrest in 50 words
Ross Gardler wrote: RG> I'd say stick with what we had I agree. No point in having a lengthy discussion. To a large extent it depends on the perspective you have and the background you come from. So if you feel happier with it, just ignore my proposal and stick with the previous text. -- Ferdinand Soethe
Re: describe Forrest in 50 words
David Crossley wrote: Ferdinand Soethe wrote: David Crossley wrote: DC> I think that it confuses people. Forrest can have multiple DC> source input formats, so this description conflicts with that. I changed that back an forth a couple of times and finally took 'formats' out. Not just because the repetition sounds bad, but mostly because to me 'input formats' suggests file of different formats (whereas I wanted to broaden the meaning to all input including databases, streams etc.) DC> I had never heard of the term, so i had to Google. DC> The results did not help to allay my concern. Yes, this may be an important issue since we also address a lot of programmers looking for documentation. How about spending an extra word on 'Apache Forrest is a standards-based framework for documentation and Single Source Publishing' Let me try to say it another way: I am very unhappy with this term "Single Source Publishing". Forrest does not restrict people to a single source. I can devise a sitemap that gets various input from many different sources and aggregates it. That is not "single source". The definition of single source publishing is that you can create many output formats from a single input format (the number on hit on google right now is http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/ this demonstrates outputting many files from a single source document). However, I see your point, it could be interpreted as meaning that Forrest only supports a single input format. There are not enough words to clarify this in this short description so we need to remove this ambiguity and it was not there in the previous version. DC> Do we really need to mention a limited list of output formats? I definitely would because these are the foundation for most publishing tasks. So here extensibility is nice, but the fact that we do HTML and PDF out of the box will be more important for perhaps 90% of the users. Or am I missing something? The limited nature of the list. Many products can output HTML and PDF. It seems to limit the idea of multiple outputs. Also, tacking the words HTML and PDF onto the end of "unified output" doesn't seem to work. HTML is a mess, not unified. Anyway, i am not going to fight that one if people want to mention specific outputs. My main gripe is the SSP. I'm with David on this one. Just as SSP could give the impression of limiting inputs the mention of HTML and PDF could give the impression of limiting outputs. I'd say stick with what we had (and I'm away from the office for most of the next two days so I'll leave it to you folk to sort out). Ross
Re: describe Forrest in 50 words
David Crossley wrote: Ferdinand Soethe wrote: Sorry to join in so late. I was busy writing a paper describing Forrest in German so in a way warming up for this :-) I commend all of you for the progress visible when following this thread. Most changes seemed to make the message clearer for ordinary users. Still, I couldn't resist to play with your version and come up with this: 'Apache Forrest is a standards-based framework for Single Source Publishing, transforming different input to unified output in formats like HTML and PDF. Its modular and extensible architecture is based on Apache Cocoon and emphasizes the strict separation of presentation and content. Forrest can generated static documents, run on an application server or be deployed by an automated publishing application.' Main change is to use "Single Source Publishing" rather then documentation because I think this is one feature where Forrest is really strong. Yet one might argue that this will confuse people who are looking for a documentation solution and don't know SSP ?! Hope it helps. It's 60 words. I think that it confuses people. In that case I may have liked it because of the work Ferdinand and I are doing on the ApacheCon presentation. I'm used to his words etc. Stick to the original if this new one is confusing. Ross
Re: describe Forrest in 50 words
Ferdinand Soethe wrote: > David Crossley wrote: > > DC> I think that it confuses people. Forrest can have multiple > DC> source input formats, so this description conflicts with that. > > I changed that back an forth a couple of times and finally took > 'formats' out. Not just because the repetition sounds bad, but mostly > because to me 'input formats' suggests file of different formats > (whereas I wanted to broaden the meaning to all input including > databases, streams etc.) > > DC> I had never heard of the term, so i had to Google. > DC> The results did not help to allay my concern. > > Yes, this may be an important issue since we also address a lot of > programmers looking for documentation. How about spending an extra > word on > > 'Apache Forrest is a standards-based framework for documentation and > Single Source Publishing' Let me try to say it another way: I am very unhappy with this term "Single Source Publishing". Forrest does not restrict people to a single source. I can devise a sitemap that gets various input from many different sources and aggregates it. That is not "single source". > DC> This term "unified output" has lost the intention > DC> of what Ross suggested earlier in this thread. > DC> So if we are not using the original meaning then > DC> i think that we should dump it. > > I wouldn't drop it because I consider the unifying function is one of > the most important features for both documentation and SSP. I figured > I could cut it short because this won't be self-explanatory for people anyway. > > Looking up the original text > > RG> "Thus Forrest can present a unified document structure and design at the > RG> output stage regardless of the chosen input formats." > > Not sure the meaning gets lost, but we can always write something like > > 'Apache Forrest is a standards-based framework for documentation and > Single Source Publishing, transforming different input to a unified > document structure and design at the output stage' That is getting back to the original idea, except for the single source bit. > DC> Do we really need to mention a limited list of output formats? > > I definitely would because these are the foundation for most > publishing tasks. So here extensibility is nice, but the fact that we > do HTML and PDF out of the box will be more important for perhaps 90% > of the users. Or am I missing something? The limited nature of the list. Many products can output HTML and PDF. It seems to limit the idea of multiple outputs. Also, tacking the words HTML and PDF onto the end of "unified output" doesn't seem to work. HTML is a mess, not unified. Anyway, i am not going to fight that one if people want to mention specific outputs. My main gripe is the SSP. --David
Re: describe Forrest in 50 words
David Crossley wrote: DC> I think that it confuses people. Forrest can have multiple DC> source input formats, so this description conflicts with that. I changed that back an forth a couple of times and finally took 'formats' out. Not just because the repetition sounds bad, but mostly because to me 'input formats' suggests file of different formats (whereas I wanted to broaden the meaning to all input including databases, streams etc.) DC> I had never heard of the term, so i had to Google. DC> The results did not help to allay my concern. Yes, this may be an important issue since we also address a lot of programmers looking for documentation. How about spending an extra word on 'Apache Forrest is a standards-based framework for documentation and Single Source Publishing' DC> This term "unified output" has lost the intention DC> of what Ross suggested earlier in this thread. DC> So if we are not using the original meaning then DC> i think that we should dump it. I wouldn't drop it because I consider the unifying function is one of the most important features for both documentation and SSP. I figured I could cut it short because this won't be self-explanatory for people anyway. Looking up the original text RG> "Thus Forrest can present a unified document structure and design at the RG> output stage regardless of the chosen input formats." Not sure the meaning gets lost, but we can always write something like 'Apache Forrest is a standards-based framework for documentation and Single Source Publishing, transforming different input to a unified document structure and design at the output stage' DC> Do we really need to mention a limited list of output formats? I definitely would because these are the foundation for most publishing tasks. So here extensibility is nice, but the fact that we do HTML and PDF out of the box will be more important for perhaps 90% of the users. Or am I missing something? -- Ferdinand Soethe
Re: describe Forrest in 50 words
Ferdinand Soethe wrote: > > Sorry to join in so late. I was busy writing a paper describing Forrest > in German so in a way warming up for this :-) > > I commend all of you for the progress visible when following this > thread. Most changes seemed to make the message clearer for ordinary > users. > > Still, I couldn't resist to play with your version and come up with > this: > > 'Apache Forrest is a standards-based framework for Single Source > Publishing, transforming different input to unified output > in formats like HTML and PDF. Its modular and extensible architecture > is based on Apache Cocoon and emphasizes the strict separation of > presentation and content. Forrest can generated static documents, run > on an application server or be deployed by an automated publishing > application.' > > Main change is to use "Single Source Publishing" rather then > documentation because I think this is one feature where > Forrest is really strong. > > Yet one might argue that this will confuse people who are looking > for a documentation solution and don't know SSP ?! > > Hope it helps. It's 60 words. I think that it confuses people. Forrest can have multiple source input formats, so this description conflicts with that. I had never heard of the term, so i had to Google. The results did not help to allay my concern. This term "unified output" has lost the intention of what Ross suggested earlier in this thread. So if we are not using the original meaning then i think that we should dump it. Do we really need to mention a limited list of output formats? --David
Re: describe Forrest in 50 words
Ferdinand Soethe wrote: Still, I couldn't resist to play with your version and come up with this: 'Apache Forrest is a standards-based framework for Single Source Publishing, transforming different input to unified output in formats like HTML and PDF. Its modular and extensible architecture is based on Apache Cocoon and emphasizes the strict separation of presentation and content. Forrest can generated static documents, run on an application server or be deployed by an automated publishing application.' Actually, I really like the sound of this. It seems to flow much better. Ross
Re: describe Forrest in 50 words
Sorry to join in so late. I was busy writing a paper describing Forrest in German so in a way warming up for this :-) I commend all of you for the progress visible when following this thread. Most changes seemed to make the message clearer for ordinary users. Still, I couldn't resist to play with your version and come up with this: 'Apache Forrest is a standards-based framework for Single Source Publishing, transforming different input to unified output in formats like HTML and PDF. Its modular and extensible architecture is based on Apache Cocoon and emphasizes the strict separation of presentation and content. Forrest can generated static documents, run on an application server or be deployed by an automated publishing application.' Main change is to use "Single Source Publishing" rather then documentation because I think this is one feature where Forrest is really strong. Yet one might argue that this will confuse people who are looking for a documentation solution and don't know SSP ?! Hope it helps. It's 60 words. -- Ferdinand Soethe
Re: describe Forrest in 50 words
David Crossley wrote: Taking the comments into account, we now have this ... Apache Forrest is a standards-based documentation framework which uses Apache Cocoon. Forrest emphasises separation of presentation and content, using a plugin architecture to transform and aggregate various input sources into various output formats. This creates a unified document collection that can either be used as a dynamic application, or generated at the command-line, or generated and deployed with an automated publishing application. The main things that are lost from previous versions are: *) The phrase "xml standards". Not so bad because surely people would expect everything to be based on xml. However, it was good fodder for search engines. I'm OK with this. XML standards is such a general term that I doubt it will bring too many visitors. Besides it can always be put in the keywords for the index page. *) The concept of a "unified document structure and design at the output stage" which implied consistent and easy generation/skinning of output formats. I'm comfortable with this too. As you say this was an implied rather than explicit interpretation. I don't think we have lost much explicit content with the above use of "unified document collection". +1 to this one, but... Juan Jose Pablos also suggests (with my minor grammar edits): Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture. This architecture transforms a variety of input sources into one or more output formats, thus enabling a unified document collection that can be hosted dynamically, generated from the command-line or deployed with an automated publishing application. I'm also +1 for this one. Ross
Re: describe Forrest in 50 words
Hi, just my 2 cents. Ross Gardler <[EMAIL PROTECTED]> writes: Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture for transforming and aggregating a variety of input sources into one or more output formats. This enables Forrest to create a unified document collection that can be hosted dynamically or generated from the command-line and deployed with an automated robot. Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture. This architecture transforms a variety of input sources into one or more output formats, so enable a unified document collection that can be hosted dynamically, generated from the command-line or deployed with an automated publishing application. WDYT?
Re: describe Forrest in 50 words
Taking the comments into account, we now have this ... Apache Forrest is a standards-based documentation framework which uses Apache Cocoon. Forrest emphasises separation of presentation and content, using a plugin architecture to transform and aggregate various input sources into various output formats. This creates a unified document collection that can either be used as a dynamic application, or generated at the command-line, or generated and deployed with an automated publishing application. The main things that are lost from previous versions are: *) The phrase "xml standards". Not so bad because surely people would expect everything to be based on xml. However, it was good fodder for search engines. *) The concept of a "unified document structure and design at the output stage" which implied consistent and easy generation/skinning of output formats. --David
Re: describe Forrest in 50 words
Brett Presnell wrote: > Ross Gardler <[EMAIL PROTECTED]> writes: > >Brett Presnell wrote: [ snip ] > >> Getting better, but I don't like the last sentence because it sounds > >> like a document collection generated from the command line would be > >> deployed with an automated robot, and I think you mean this the other > >> way around > > > > Nope, that is exactly what I mean. See > > http://forrest.apache.org/proposal-asf-forrestbot.html (we have > > documentation on teh forrestbot but it seems to have disppeared from > > the website in our recent reogranisation). It is there getting ready for the release: http://forrest.apache.org/0.7/docs/forrestbot.html > Hmmm, so robot != tomcat after all, and instead robot == forrestbot? Since you phrased it as a question, the answer is yes. > In my own usage I was using forrest with tomcat for development, but > for deployment I would generate a static version, and so I identified > "generated from the command-line" with static. Forrestbot never > really entered my conciousness. There are various methods for Forrest: *) Dynamic application: local webapp for quick edit/view/review aka 'forrest run' (uses the packaged Jetty server). *) Dynamic application: as a webapp runnng in Jetty/Tomcat/etc. *) Command-line: generate a complete static document collection aka 'forrest'. *) Forrestbot: automated building and deployment of a complete static document collection. It can be run via cron or has a webapp interface to enable triggering the build/deploy and for viewing the log output. We are trying to cram that into one sentence :-) > But, considering my usage as an example, isn't it true that the robot > is a somewhat separate issue from static versus dynamic. The current > wording makes it sound like the only options are dynamically hosted or > deployed with a robot. I think that's what was indirectly causing my > confusion, since I knew there was another possibility. Thanks for your help Brett. All contributions will go into the mix. --David
Re: describe Forrest in 50 words
Ross Gardler <[EMAIL PROTECTED]> writes: >> >>>Apache Forrest is a standards-based documentation framework based >>>on Apache Cocoon. Forrest emphasizes separation of presentation >>>and content through a plugin architecture for transforming and >>>aggregating a variety of input sources into one or more output >>>formats. This enables Forrest to create a unified document collection >>>that can be hosted dynamically or generated from the command-line and >>>deployed with an automated robot. >> Getting better, but I don't like the last sentence because it sounds >> like a document collection generated from the command line would be >> deployed with an automated robot, and I think you mean this the other >> way around > > Nope, that is exactly what I mean. See > http://forrest.apache.org/proposal-asf-forrestbot.html (we have > documentation on teh forrestbot but it seems to have disppeared from > the website in our recent reogranisation). Hmmm, so robot != tomcat after all, and instead robot == forrestbot? In my own usage I was using forrest with tomcat for development, but for deployment I would generate a static version, and so I identified "generated from the command-line" with static. Forrestbot never really entered my conciousness. But, considering my usage as an example, isn't it true that the robot is a somewhat separate issue from static versus dynamic. The current wording makes it sound like the only options are dynamically hosted or deployed with a robot. I think that's what was indirectly causing my confusion, since I knew there was another possibility. -- Brett Presnell Department of Statistics University of Florida http://www.stat.ufl.edu/~presnell/ "We don't think that the popularity of an error makes it the truth." -- Richard Stallman () ascii ribbon campaign - against html mail /\- against microsoft attachments
Re: describe Forrest in 50 words
Brett Presnell wrote: Ross Gardler <[EMAIL PROTECTED]> writes: Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture for transforming and aggregating a variety of input sources into one or more output formats. This enables Forrest to create a unified document collection that can be hosted dynamically or generated from the command-line and deployed with an automated robot. Getting better, but I don't like the last sentence because it sounds like a document collection generated from the command line would be deployed with an automated robot, and I think you mean this the other way around Nope, that is exactly what I mean. See http://forrest.apache.org/proposal-asf-forrestbot.html (we have documentation on teh forrestbot but it seems to have disppeared from the website in our recent reogranisation). Actually, I'm not sure that most potential users having a first look at forrest would know what you mean by "robot", and they might even find it off-putting. It's ok, but is there some other word that would be less mysterious and still serve the purpose? Well if you, as a user, find it mysterious that's a problem. Furthermore, if you, as a user with some knowledge of Forrest, can misinterpret it then there is clearly a problem with the last sentence :-) How about replacing "automated robot" with "automated publishing application"? Increases our word count by one but if we get more clarity as a result I think it is worth it. Anyway, I'll probably check out now. Good luck, and thanks to all of you for your work on forrest. Thanks for your feedback, it is extremely valuable to us. We hope to see more of you. Ross
Re: describe Forrest in 50 words
Ross Gardler <[EMAIL PROTECTED]> writes: > > Apache Forrest is a standards-based documentation framework based > on Apache Cocoon. Forrest emphasizes separation of presentation > and content through a plugin architecture for transforming and > aggregating a variety of input sources into one or more output > formats. This enables Forrest to create a unified document collection > that can be hosted dynamically or generated from the command-line and > deployed with an automated robot. Getting better, but I don't like the last sentence because it sounds like a document collection generated from the command line would be deployed with an automated robot, and I think you mean this the other way around (it has been a while since I was messing with forrest, but I assume the robot you have in mind is tomcat). How about this (still 62 words)?: Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture for transforming and aggregating a variety of input sources into one or more output formats. This enables Forrest to create a unified document collection that can be generated from the command-line or hosted dynamically and deployed with an automated robot. Actually, I'm not sure that most potential users having a first look at forrest would know what you mean by "robot", and they might even find it off-putting. It's ok, but is there some other word that would be less mysterious and still serve the purpose? Anyway, I'll probably check out now. Good luck, and thanks to all of you for your work on forrest. -- Brett Presnell Department of Statistics University of Florida http://www.stat.ufl.edu/~presnell/ "We don't think that the popularity of an error makes it the truth." -- Richard Stallman () ascii ribbon campaign - against html mail /\- against microsoft attachments
Re: describe Forrest in 50 words
:) Nice one, Brett, and welcome to forrest. I only would change just one sentence. On Wed, 2005-04-20 at 07:03 -0400, Brett Presnell wrote: > David Crossley <[EMAIL PROTECTED]> writes: > > > > Here is the proposal so far .. > > > > Apache Forrest is an XML standards-oriented documentation > > framework based upon Apache Cocoon and separation of concerns. > > Using a plugin architecture, various source input formats are > > transformed and aggregated with other sources into various > > output formats. This presents a unified document structure > > and design at the output stage. Forrest can be used as a > > dynamic application, or can generate sets of documents via > > the command-line, and deploy with an automated robot. > > > > > > That is 70 words. Looking at the other project > > descriptions at www.apache.org/foundation/projects.html > > that puts us second behind Cocoon (77) and in front of > > Struts (65). > > > > Does anyone have more comments? We need to target the > > description somewhere between the user and developer. > > As a one-time and, I hope, future user of forrest, I thought I might > try to chip in here. Taking David's version as my starting point, my > attempt comes to 49 words: > >Apache Forrest is a standards-based documentation framework based >on Apache Cocoon. Forrest emphasizes separation of presentation >and content, using a plugin architecture to transform and aggregate >a variety of input formats into a unified document which may be >generated statically or dynamically from sources. Output formats >include HTML and PDF. The following sentence seems to be too focused on pdf/html Output formats >include HTML and PDF. Maybe something *like* this: Forrest supports a wide range of output formats (html, pdf,...). Cheers for the feedback (and we hope you stay). ;-) -- thorsten "Together we stand, divided we fall!" Hey you (Pink Floyd)
Re: describe Forrest in 50 words
Brett Presnell wrote: David Crossley <[EMAIL PROTECTED]> writes: Here is the proposal so far .. Apache Forrest is an XML standards-oriented documentation framework based upon Apache Cocoon and separation of concerns. Using a plugin architecture, various source input formats are transformed and aggregated with other sources into various output formats. This presents a unified document structure and design at the output stage. Forrest can be used as a dynamic application, or can generate sets of documents via the command-line, and deploy with an automated robot. That is 70 words. Looking at the other project descriptions at www.apache.org/foundation/projects.html that puts us second behind Cocoon (77) and in front of Struts (65). Does anyone have more comments? We need to target the description somewhere between the user and developer. As a one-time and, I hope, future user of forrest, I thought I might try to chip in here. Excellent, you are exactly the kind of person we need feedback from. Thanks. Taking David's version as my starting point, my attempt comes to 49 words: Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content, using a plugin architecture to transform and aggregate a variety of input formats into a unified document which may be generated statically or dynamically from sources. Output formats include HTML and PDF. I like where this is going. My observations are: - "unified document" implies a single document which is not always true. We have also lost the emphasis that we create multiple output documents. - we've lost the idea of "deployment by an automated robot" which is very important for many of our current and potential users. - the last sentence seems unimportant as this will be prominent in a features list and I expect most users would expect those two formats. This makes my slightly modified version come out at 62 words (brings us under the struts Benchmark, but takes us back over the magic 50 word mark, over to someone else to bring it back down again - which part of my addition is unimportant?) : Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content through a plugin architecture for transforming and aggregating a variety of input sources into one or more output formats. This enables Forrest to create a unified document collection that can be hosted dynamically or generated from the command-line and deployed with an automated robot. Ross
Re: describe Forrest in 50 words
David Crossley <[EMAIL PROTECTED]> writes: > > Here is the proposal so far .. > > Apache Forrest is an XML standards-oriented documentation > framework based upon Apache Cocoon and separation of concerns. > Using a plugin architecture, various source input formats are > transformed and aggregated with other sources into various > output formats. This presents a unified document structure > and design at the output stage. Forrest can be used as a > dynamic application, or can generate sets of documents via > the command-line, and deploy with an automated robot. > > > That is 70 words. Looking at the other project > descriptions at www.apache.org/foundation/projects.html > that puts us second behind Cocoon (77) and in front of > Struts (65). > > Does anyone have more comments? We need to target the > description somewhere between the user and developer. As a one-time and, I hope, future user of forrest, I thought I might try to chip in here. Taking David's version as my starting point, my attempt comes to 49 words: Apache Forrest is a standards-based documentation framework based on Apache Cocoon. Forrest emphasizes separation of presentation and content, using a plugin architecture to transform and aggregate a variety of input formats into a unified document which may be generated statically or dynamically from sources. Output formats include HTML and PDF. I'm sure this needs more work, but I think it would be clearer to a user like me. It is probably not as complete or precise as the developers might like, but I think that it is worth keeping in mind that a short description like this must necessarily sacrifice something in detail and precision in order to succinctly get the main points across. For me personally, the biggest shortcoming of this version is that it doesn't make clear (at least to me) that Forrest can be used as a sort of CMS replacement for managing a (relatively simple) web site, which is my main interest. However, David did not emphasize this aspect of forrest either, and recognizing that some things must be sacrificed in a short description, I decided to follow his lead. BTW, I won't be offended if you don't want to use any part of my version. I don't have any reason to be sensitive about it, particulary since my expertise in all this is very limited. -- Brett Presnell Department of Statistics University of Florida http://www.stat.ufl.edu/~presnell/ "We don't think that the popularity of an error makes it the truth." -- Richard Stallman () ascii ribbon campaign - against html mail /\- against microsoft attachments
Re: describe Forrest in 50 words
Ross Gardler wrote: > David Crossley wrote: > >A while ago we discussed our description of Forrest > >and concluded that it was a bit limiting. > > > >Actually trying to concisely summarise Forrest > >is a very difficult task. [ snip ] > > Two points, one a possible addition, the other a possible red herring. > > [OT: does "red herring" make sense to the non-English speakers here, I'm > not sure it would work in a literal translation?, just in case it means > "A distractor that draws attention away from the real issue." > (http://csmp.ucop.edu/crlp/resources/glossary.html)] > > First the possible Red Herring: > > Highlighting the "internal format" concept we may be asking for trouble. > This appears to be the most common cause for concern for new > users/developers. For example, "what is it?", "wouldn't XYZ be a better > format?", "why do we need one?", and by far the most common "won't we > lose semantic clarity?". Good catch. Yes this is intended to be a high-level description. To address those issues we need to enhance our own Forrest "Contract" documentation. > I would consider simply removing the reference to the internal format > and focus on the transformation from one format to another. > > Secondly the potential addition? The trouble is that we are already way over 50 words :-) Never mind. Better to properly describe. > Perhaps add something like: > > "Thus Forrest can present a unified document structure and design at the > output stage regardless of the chosen input formats." Here is the proposal so far .. Apache Forrest is an XML standards-oriented documentation framework based upon Apache Cocoon and separation of concerns. Using a plugin architecture, various source input formats are transformed and aggregated with other sources into various output formats. This presents a unified document structure and design at the output stage. Forrest can be used as a dynamic application, or can generate sets of documents via the command-line, and deploy with an automated robot. That is 70 words. Looking at the other project descriptions at www.apache.org/foundation/projects.html that puts us second behind Cocoon (77) and in front of Struts (65). Does anyone have more comments? We need to target the description somewhere between the user and developer. There is one particular comment from our email archives that i have tried to bear in mind while altering the description. They said that Forrest was too focussed on web documentation and neglected other situations, e.g. report generation. The two references to "web" are now removed. --David
Re: describe Forrest in 50 words
David Crossley wrote: A while ago we discussed our description of Forrest and concluded that it was a bit limiting. Actually trying to concisely summarise Forrest is a very difficult task. Here is what is was ... Apache Forrest is an XML standards-oriented documentation framework based upon Apache Cocoon, providing XSLT stylesheets and schemas, images and other resources. Forrest uses these to render the source content into a website via command-line, robot, or dynamic application. Here is my proposal so far ... Apache Forrest is an XML standards-oriented documentation framework based upon Apache Cocoon and separation of concerns. Using a plugin architecture, various source input formats are transformed into a common internal format, aggregated with other sources, and transformed into various output formats. Forrest can be used as a dynamic application or can generate sets of documents via the command-line and deploy with an automated robot. Two points, one a possible addition, the other a possible red herring. [OT: does "red herring" make sense to the non-English speakers here, I'm not sure it would work in a literal translation?, just in case it means "A distractor that draws attention away from the real issue." (http://csmp.ucop.edu/crlp/resources/glossary.html)] First the possible Red Herring: Highlighting the "internal format" concept we may be asking for trouble. This appears to be the most common cause for concern for new users/developers. For example, "what is it?", "wouldn't XYZ be a better format?", "why do we need one?", and by far the most common "won't we lose semantic clarity?". I would consider simply removing the reference to the internal format and focus on the transformation from one format to another. Secondly the potential addition? Perhaps add something like: "Thus Forrest can present a unified document structure and design at the output stage regardless of the chosen input formats." Ross
Re: describe Forrest in 50 words
Sounds good. :) +1 salu2 On Mon, 2005-04-18 at 11:03 +1000, David Crossley wrote: > A while ago we discussed our description of Forrest > and concluded that it was a bit limiting. > > Actually trying to concisely summarise Forrest > is a very difficult task. > > Here is what is was ... > > Apache Forrest is an XML standards-oriented documentation framework > based upon Apache Cocoon, providing XSLT stylesheets and schemas, > images and other resources. Forrest uses these to render the source > content into a website via command-line, robot, or dynamic application. > > > Here is my proposal so far ... > > Apache Forrest is an XML standards-oriented documentation framework > based upon Apache Cocoon and separation of concerns. Using a plugin > architecture, various source input formats are transformed into a > common internal format, aggregated with other sources, and > transformed into various output formats. Forrest can be used as > a dynamic application or can generate sets of documents via the > command-line and deploy with an automated robot. > -- thorsten "Together we stand, divided we fall!" Hey you (Pink Floyd)
