You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by "Andrew C. Oliver" <ac...@apache.org> on 2002/07/12 16:04:34 UTC
Documentation and abbreviations
Hi All,
this is mostly a pedantic issue. But one thing that bugs me about much
of the existing cocoon documentation is the style in which
Cocoon-specific abbreviations are used. A good example:
http://xml.apache.org/cocoon/userdocs/xsp/index.html
The most basic question is "What does XSP stand for?" From there, one
could almost guess what it is essentially. My suggestion to
documentation writers is that when using an abbreviation think "Is the
standard Java developer using Cocoon for the first time going to know
what this means".
My suggestion in the case they won't, use an abbreviation introduction
for the first use in the document as follows:
---
Here will soon appear an overview of the user perspective of eXtensible
Server Pages (XSP).
---
from then on its safe to use the abbreviation and the reader will know
what you mean.
I believe that doing this will prevent Cocoon documentation from reading
like an eyechart ;-)
-Andy
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by "Andrew C. Oliver" <ac...@apache.org>.
Steven Noels wrote:
> Andrew C. Oliver wrote:
>
>> Here is my first entry :-)
>>
>> <glossary>
>> <entry>
>> <phrase>Cocoon Syndrome</phrase>
>> <meaning>The tendancy whenever anything regarding
>> documentation to focus on a tool for doing the documentation function
>> than actually producing content. Generally
>> resulting in long threads with good ideas that will probably never be
>> implemented, however no actual documentation.
>> It is preferrable for these ideas to require far more effort than they
>> would actually save. </menaing>
>> </entry>
>> </glossary>
>
>
> <treatment>forrest-dev@xml.apache.org</treatment>
bzzzzt. A tool does not treat cocoon syndrome. More tools (especially
undocumented tools) without documentation are the very etymology of
cocoon syndrome :-)
>
> :-D
>
> </Steven>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Steven Noels <st...@outerthought.org>.
Andrew C. Oliver wrote:
> Here is my first entry :-)
>
> <glossary>
> <entry>
> <phrase>Cocoon Syndrome</phrase>
> <meaning>The tendancy whenever anything regarding documentation
> to focus on a tool for doing the documentation function
> than actually producing content. Generally
> resulting in long threads with good ideas that will probably never be
> implemented, however no actual documentation. It
> is preferrable for these ideas to require far more effort than they
> would actually save. </menaing>
> </entry>
> </glossary>
<treatment>forrest-dev@xml.apache.org</treatment>
:-D
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by "Andrew C. Oliver" <ac...@apache.org>.
Nicola Ken Barozzi wrote:
> Andrew C. Oliver wrote:
>
>> Steven Noels wrote:
>>
>>>
>>> *All* instances? Hm. Wouldn't that be troublesome to read? Reminds
>>> me of Wiki webs where people where triggerhappy with hyperreferences.
>>>
>>> A thesaurus of some sorts, easily reachable from each page, might
>>> perhaps already be enough.
>>>
>>> </Steven>
>>
>>
>>
>> Here is my first entry :-)
>
>
> Please resubmit, the xml is not well formed ;-PPP
Perhaps we could work on a resubmission tool that would simulate me
smacking you as I fix the tag and resend it
Lets identify the Avalon components.
NicolaKenSmacker (extends Smacker which extends AbstractSmacker which
extends ViolentResponse which extends AbstractViolentResponse which
extends ActionResponse which extends AbstractActionResponse which
extends Response which extends Component)
TagFixer (...see above...kinda like that only supports the TagInterface)
SarcasticMailAction... ;-)
:-D
-Andy
>
>> <glossary>
>> <entry>
>> <phrase>Cocoon Syndrome</phrase>
>> <meaning>The tendancy whenever anything regarding
>> documentation to focus on a tool for doing the documentation function
>> than actually producing content. Generally
>> resulting in long threads with good ideas that will probably never be
>> implemented, however no actual documentation.
>> It is preferrable for these ideas to require far more effort than they
>> would actually save. </menaing>
>
> ^^^^^^^^^^^^^^^
>
>> </entry>
>> </glossary>
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andrew C. Oliver wrote:
> Steven Noels wrote:
>
>>
>> *All* instances? Hm. Wouldn't that be troublesome to read? Reminds me
>> of Wiki webs where people where triggerhappy with hyperreferences.
>>
>> A thesaurus of some sorts, easily reachable from each page, might
>> perhaps already be enough.
>>
>> </Steven>
>
>
> Here is my first entry :-)
Please resubmit, the xml is not well formed ;-PPP
> <glossary>
> <entry>
> <phrase>Cocoon Syndrome</phrase>
> <meaning>The tendancy whenever anything regarding documentation
> to focus on a tool for doing the documentation function
> than actually producing content. Generally
> resulting in long threads with good ideas that will probably never be
> implemented, however no actual documentation. It
> is preferrable for these ideas to require far more effort than they
> would actually save. </menaing>
^^^^^^^^^^^^^^^
> </entry>
> </glossary>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by "Andrew C. Oliver" <ac...@apache.org>.
Steven Noels wrote:
>
> *All* instances? Hm. Wouldn't that be troublesome to read? Reminds me
> of Wiki webs where people where triggerhappy with hyperreferences.
>
> A thesaurus of some sorts, easily reachable from each page, might
> perhaps already be enough.
>
> </Steven>
Here is my first entry :-)
<glossary>
<entry>
<phrase>Cocoon Syndrome</phrase>
<meaning>The tendancy whenever anything regarding documentation
to focus on a tool for doing the documentation function
than actually producing content. Generally
resulting in long threads with good ideas that will probably never be
implemented, however no actual documentation.
It is preferrable for these ideas to require far more effort than they
would actually save.
</menaing>
</entry>
</glossary>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Steven Noels <st...@outerthought.org>.
Nicola Ken Barozzi wrote:
> Even better, we make a link creating Transformer that transforms all
> instances of " xsp " to a link that links to a cocoon terms dictionary.
>
*All* instances? Hm. Wouldn't that be troublesome to read? Reminds me of
Wiki webs where people where triggerhappy with hyperreferences.
A thesaurus of some sorts, easily reachable from each page, might
perhaps already be enough.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
stevenn@outerthought.org stevenn@apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Bert Van Kets <we...@classicfighters.com>.
At 15:32 12/07/2002 -0500, you wrote:
>Bert Van Kets wrote:
>
>>this is a great idea if implemented properly. I hate being moved to a
>>new page just clicking on a link on an abbreviation.
>>I see different implementations
>>1. a link to a footnote on the same place where the abbreviation is
>>explained. At least the user would stay on the same page.
>>2. a javascript alert that gives the full explanation
>>3. use of the title attribute
>>(http://www.w3.org/TR/html4/struct/global.html#adef-title), but then
>>there is a non-functioning link on the abbreviation
>>4. a link to a new window and anchor containing the explanation, perhaps
>>sized using the JavaScript window.open command
>>5. a link and anchor in the same window (beurk) definitely a -1 from me
>
>
><acronym title="eXtensible Server Pages">XSP</acronym>
>
>See
>http://diveintomark.org/archives/2002/07/02.html#day_17_defining_acronyms
>for more goods.
>
>Tony
That's a great tip
Thanks,
Bert
>---------------------------------------------------------------------
>To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Tony Collen <tc...@hist.umn.edu>.
Bert Van Kets wrote:
> this is a great idea if implemented properly. I hate being moved to a
> new page just clicking on a link on an abbreviation.
> I see different implementations
> 1. a link to a footnote on the same place where the abbreviation is
> explained. At least the user would stay on the same page.
> 2. a javascript alert that gives the full explanation
> 3. use of the title attribute
> (http://www.w3.org/TR/html4/struct/global.html#adef-title), but then
> there is a non-functioning link on the abbreviation
> 4. a link to a new window and anchor containing the explanation,
> perhaps sized using the JavaScript window.open command
> 5. a link and anchor in the same window (beurk) definitely a -1 from me
<acronym title="eXtensible Server Pages">XSP</acronym>
See
http://diveintomark.org/archives/2002/07/02.html#day_17_defining_acronyms
for more goods.
Tony
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
RE: Documentation and abbreviations
Posted by Vadim Gritsenko <va...@verizon.net>.
> From: Bert Van Kets [mailto:bert@vankets.com]
>
> At 16:19 12/07/2002 +0200, you wrote:
> >Andrew C. Oliver wrote:
> >>Hi All,
> >>this is mostly a pedantic issue. But one thing that bugs me about
much
> >>of the existing cocoon documentation is the style in which
> >>Cocoon-specific abbreviations are used. A good example:
> >>http://xml.apache.org/cocoon/userdocs/xsp/index.html
> >>The most basic question is "What does XSP stand for?" From there,
one
> >>could almost guess what it is essentially. My suggestion to
> >>documentation writers is that when using an abbreviation think "Is
the
> >>standard Java developer using Cocoon for the first time going to
know
> >>what this means".
> >>My suggestion in the case they won't, use an abbreviation
introduction
> >>for the first use in the document as follows:
> >>---
> >>Here will soon appear an overview of the user perspective of
eXtensible
> >>Server Pages (XSP).
> >>---
> >>from then on its safe to use the abbreviation and the reader will
know
> >>what you mean. I believe that doing this will prevent Cocoon
> >>documentation from reading like an eyechart ;-)
> >
> >Even better, we make a link creating Transformer that transforms all
> >instances of " xsp " to a link that links to a cocoon terms
dictionary.
>
> this is a great idea if implemented properly. I hate being moved to a
new
> page just clicking on a link on an abbreviation.
> I see different implementations
> 1. a link to a footnote on the same place where the abbreviation is
> explained. At least the user would stay on the same page.
> 2. a javascript alert that gives the full explanation
> 3. use of the title attribute
> (http://www.w3.org/TR/html4/struct/global.html#adef-title), but then
there
> is a non-functioning link on the abbreviation
???
<span title="eXtensible Server Pages>XSP</span>
http://www.w3.org/TR/html4/struct/global.html#h-7.5.4
PS Why not <acronym/>?
Vadim
> 4. a link to a new window and anchor containing the explanation,
perhaps
> sized using the JavaScript window.open command
> 5. a link and anchor in the same window (beurk) definitely a -1 from
me
>
> I thing it should be possible to use XSLT for this, but it might be
> slooooooooow as every text node needs to be tested for every
> abbreviation. Sadly enough my Java knowledge is not up to speed yet.
>
> Bert
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Bert Van Kets <be...@vankets.com>.
At 16:19 12/07/2002 +0200, you wrote:
>Andrew C. Oliver wrote:
>>Hi All,
>>this is mostly a pedantic issue. But one thing that bugs me about much
>>of the existing cocoon documentation is the style in which
>>Cocoon-specific abbreviations are used. A good example:
>>http://xml.apache.org/cocoon/userdocs/xsp/index.html
>>The most basic question is "What does XSP stand for?" From there, one
>>could almost guess what it is essentially. My suggestion to
>>documentation writers is that when using an abbreviation think "Is the
>>standard Java developer using Cocoon for the first time going to know
>>what this means".
>>My suggestion in the case they won't, use an abbreviation introduction
>>for the first use in the document as follows:
>>---
>>Here will soon appear an overview of the user perspective of eXtensible
>>Server Pages (XSP).
>>---
>>from then on its safe to use the abbreviation and the reader will know
>>what you mean. I believe that doing this will prevent Cocoon
>>documentation from reading like an eyechart ;-)
>
>Even better, we make a link creating Transformer that transforms all
>instances of " xsp " to a link that links to a cocoon terms dictionary.
this is a great idea if implemented properly. I hate being moved to a new
page just clicking on a link on an abbreviation.
I see different implementations
1. a link to a footnote on the same place where the abbreviation is
explained. At least the user would stay on the same page.
2. a javascript alert that gives the full explanation
3. use of the title attribute
(http://www.w3.org/TR/html4/struct/global.html#adef-title), but then there
is a non-functioning link on the abbreviation
4. a link to a new window and anchor containing the explanation, perhaps
sized using the JavaScript window.open command
5. a link and anchor in the same window (beurk) definitely a -1 from me
I thing it should be possible to use XSLT for this, but it might be
slooooooooow as every text node needs to be tested for every
abbreviation. Sadly enough my Java knowledge is not up to speed yet.
Bert
>--
>Nicola Ken Barozzi nicolaken@apache.org
> - verba volant, scripta manent -
> (discussions get forgotten, just code remains)
>---------------------------------------------------------------------
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
>For additional commands, email: cocoon-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andrew C. Oliver wrote:
> Hi All,
>
> this is mostly a pedantic issue. But one thing that bugs me about much
> of the existing cocoon documentation is the style in which
> Cocoon-specific abbreviations are used. A good example:
>
> http://xml.apache.org/cocoon/userdocs/xsp/index.html
>
> The most basic question is "What does XSP stand for?" From there, one
> could almost guess what it is essentially. My suggestion to
> documentation writers is that when using an abbreviation think "Is the
> standard Java developer using Cocoon for the first time going to know
> what this means".
>
> My suggestion in the case they won't, use an abbreviation introduction
> for the first use in the document as follows:
>
> ---
>
> Here will soon appear an overview of the user perspective of eXtensible
> Server Pages (XSP).
>
> ---
>
> from then on its safe to use the abbreviation and the reader will know
> what you mean.
> I believe that doing this will prevent Cocoon documentation from reading
> like an eyechart ;-)
Even better, we make a link creating Transformer that transforms all
instances of " xsp " to a link that links to a cocoon terms dictionary.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: Documentation and abbreviations
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Andrew C. Oliver wrote:
> Hi All,
>
> this is mostly a pedantic issue. But one thing that bugs me about much
> of the existing cocoon documentation is the style in which
> Cocoon-specific abbreviations are used. A good example:
>
> http://xml.apache.org/cocoon/userdocs/xsp/index.html
>
> The most basic question is "What does XSP stand for?" From there, one
> could almost guess what it is essentially. My suggestion to
> documentation writers is that when using an abbreviation think "Is the
> standard Java developer using Cocoon for the first time going to know
> what this means".
>
> My suggestion in the case they won't, use an abbreviation introduction
> for the first use in the document as follows:
>
> ---
>
> Here will soon appear an overview of the user perspective of eXtensible
> Server Pages (XSP).
>
> ---
>
> from then on its safe to use the abbreviation and the reader will know
> what you mean.
> I believe that doing this will prevent Cocoon documentation from reading
> like an eyechart ;-)
Even better, we make a link creating Transformer that transforms all
instances of " xsp " to a link that links to a cocoon terms dictionary.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------