You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Victor Mote <vi...@outfitr.com> on 2003/05/13 20:43:25 UTC
release-website synchronization
While trying to sort out the issue of what our graphics support should and
should not reasonably be expected to do, the issue of how our web site
synchronizes with our releases has come up, and I would like to clarify how
this should work. There are at least three possibilities:
1. Reflects current CVS.
Pros: Keeps the flow of doc consistent with the flow of development.
Cons: Requires either a general warning telling the user to look at
distribution documentation instead of the website, or more specific comments
within the content that say things like "PDF encryption support is available
starting with 0.20.5".
2. Reflects latest Release Candidate. Pros and cons similar to Stable
Release.
3. Reflects latest Stable Release.
Pros: Either this or the Release Candidate option probably most closely
fits the user's expectations (??).
Cons: Requires either that the web site be at least partially frozen, or
that developers wait to document new items until near a release point. As a
practical matter, probably requires a system to keep track of doc changes to
be made before the next release.
I have been operating as if #1 were the policy, and that gets my +1. If you
agree, I will add some appropriate warnings to the graphics & pdf encryption
pages at least. If not, we probably need to discuss how doc should flow
through our system. In any case, I hope to document :-) the decision & the
ramifications as settled matters.
Victor Mote (mailto:vic@outfitr.com)
2025 Eddington Way
Colorado Springs, Colorado 80916
Voice +1 (719) 622-0650
Fax +1 (720) 293-0044
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: release-website synchronization
Posted by Victor Mote <vi...@outfitr.com>.
Ralph LaChance wrote:
> Standing back two paces, I'm thinking that gettng
> the new design out the door is the single best
> thing we can do on our users' behalf - I suppose
> anything that hastens that -- albeit introduce
> some untidiness - is Goodness.
Agreed. And we can always change it if it doesn't work well.
I have added some comments documenting these decisions to the Doc Mgmt page,
in the hope that it makes our work more consistent.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: release-website synchronization
Posted by Ralph LaChance <Ra...@compuserve.com>.
Your points are very well articulated.
Standing back two paces, I'm thinking that gettng
the new design out the door is the single best
thing we can do on our users' behalf - I suppose
anything that hastens that -- albeit introduce
some untidiness - is Goodness.
At 02:37 AM 5/14/2003, you wrote:
>
>Ralph LaChance wrote:
>
> > I mildly disagree w/ option #1. IMHO the web site content per se
> > is for our
> > consumers, it is not specifically for the benefit of the
> > developers. Seems
> > to me the WIKI's and the CVS tree itself are the proper place for
> > development documentation that tracks the work.
>
>We really use it both ways, but I have been working at making a stronger
>distinction between user- and developer-oriented content (moving class names
>& such from the user- to the developer- doc). I am primarily addressing just
>the user-oriented content in my question.
>
> > To my mind the web content should exactly reflect the latest downloadable
> > ~release.~ If our users read one thing on the web page and get something
> > different when they install the ~release~ -- well - you get my
> > drift. The use
> > of warnings reminds me of "if it is Tuesday and your socks are yellow...."
>
>This is a valid concern, except that I think it is much more linear than the
>Tuesday / yellow socks example. I /think/ it should generally be "If you are
>using release 0.20.4 or later ...", which is uni-dimensional and
>uni-directional.
>
>Also, it may not be very obtrusive. I can only think of two places where it
>is an issue now (PDF encryption and graphics), one applying to an entire
>document, the other to an entire section of a document. Hopefully short and
>sweet.
>
> > Would it be ridiculous (or too much work) to have the web content have
> > a "current documentation" and "in-progress changes node" ?
> > Barring that, I'd vote for door #3 - track the stable release
>
>That is the scenario that I envisioned for managing choices 2 or 3 -- a page
>in the developer section where a developer would document a change that
>needed to be documented (at the last minute) before the next release. The
>big problem with this is that people running CVS or a release candidate
>would have to know how to go find the "extra" doc. This is what I have been
>trying to pull away from. For example, until recently, to get a complete
>picture of graphics doc, you had to look at the FAQs, Release Notes, and SVG
>doc. You can still get to the content through any of those doors, but the
>logical one ("graphics") now has all of it. My current thinking is that it
>is less obtrusive to try to gather the information into one place and help
>the user sort through a few special cases than it is to spread the doc out
>based on those special cases.
>
>It might be fun to embed some javascript that shows/hides content based on
>the release in which a user is interested, but I think it is probably
>actually useful for everyone to be able to see the new, experimental,
>unreleased stuff. To a large extent, we want them, where possible, to
>download the latest greatest stuff and give us feedback.
>
>Victor Mote
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
>For additional commands, email: fop-dev-help@xml.apache.org
' Best,
-Ralph LaChance
In theory, there is no difference between
theory and practice, but in practice there is.
(Jan L.A. van de Snepsheut (1953-1994), late of CalTech)
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: release-website synchronization
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Ralph LaChance wrote:
> Would it be ridiculous (or too much work) to have the web content have
> a "current documentation" and "in-progress changes node" ?
> Barring that, I'd vote for door #3 - track the stable release
Not really ridiculous but quite a bit of work: the documentation
for the latest release needs serious maintenance too, for example
adding FAQs. Unless we find a framework which allows sharing of
common documentation snippets between the docs for the latest
stable release and the latest CVS one or the other will detoriate.
J.Pietschmann
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: release-website synchronization
Posted by Victor Mote <vi...@outfitr.com>.
Ralph LaChance wrote:
> I mildly disagree w/ option #1. IMHO the web site content per se
> is for our
> consumers, it is not specifically for the benefit of the
> developers. Seems
> to me the WIKI's and the CVS tree itself are the proper place for
> development documentation that tracks the work.
We really use it both ways, but I have been working at making a stronger
distinction between user- and developer-oriented content (moving class names
& such from the user- to the developer- doc). I am primarily addressing just
the user-oriented content in my question.
> To my mind the web content should exactly reflect the latest downloadable
> ~release.~ If our users read one thing on the web page and get something
> different when they install the ~release~ -- well - you get my
> drift. The use
> of warnings reminds me of "if it is Tuesday and your socks are yellow...."
This is a valid concern, except that I think it is much more linear than the
Tuesday / yellow socks example. I /think/ it should generally be "If you are
using release 0.20.4 or later ...", which is uni-dimensional and
uni-directional.
Also, it may not be very obtrusive. I can only think of two places where it
is an issue now (PDF encryption and graphics), one applying to an entire
document, the other to an entire section of a document. Hopefully short and
sweet.
> Would it be ridiculous (or too much work) to have the web content have
> a "current documentation" and "in-progress changes node" ?
> Barring that, I'd vote for door #3 - track the stable release
That is the scenario that I envisioned for managing choices 2 or 3 -- a page
in the developer section where a developer would document a change that
needed to be documented (at the last minute) before the next release. The
big problem with this is that people running CVS or a release candidate
would have to know how to go find the "extra" doc. This is what I have been
trying to pull away from. For example, until recently, to get a complete
picture of graphics doc, you had to look at the FAQs, Release Notes, and SVG
doc. You can still get to the content through any of those doors, but the
logical one ("graphics") now has all of it. My current thinking is that it
is less obtrusive to try to gather the information into one place and help
the user sort through a few special cases than it is to spread the doc out
based on those special cases.
It might be fun to embed some javascript that shows/hides content based on
the release in which a user is interested, but I think it is probably
actually useful for everyone to be able to see the new, experimental,
unreleased stuff. To a large extent, we want them, where possible, to
download the latest greatest stuff and give us feedback.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: release-website synchronization
Posted by Ralph LaChance <Ra...@compuserve.com>.
Hi there,
I mildly disagree w/ option #1. IMHO the web site content per se is for our
consumers, it is not specifically for the benefit of the developers. Seems
to me the WIKI's and the CVS tree itself are the proper place for
development documentation that tracks the work.
To my mind the web content should exactly reflect the latest downloadable
~release.~ If our users read one thing on the web page and get something
different when they install the ~release~ -- well - you get my drift. The use
of warnings reminds me of "if it is Tuesday and your socks are yellow...."
Would it be ridiculous (or too much work) to have the web content have
a "current documentation" and "in-progress changes node" ?
Barring that, I'd vote for door #3 - track the stable release
At 03:03 PM 5/13/2003, you wrote:
>
>
>On 13.05.2003 20:43:25 Victor Mote wrote:
> > 1. Reflects current CVS.
> > Pros: Keeps the flow of doc consistent with the flow of development.
> > Cons: Requires either a general warning telling the user to look at
> > distribution documentation instead of the website, or more specific
> comments
> > within the content that say things like "PDF encryption support is
> available
> > starting with 0.20.5".
>
>+1
>
>Only think about the current situation where some deficiencies are found.
>You want them fixed as soon as possible.
>
>Thanks for taking care of the comments.
>
>
>
>While we're discussing the website:
>What would you think about a Who-we-are page like the one from Batik?
>http://xml.apache.org/batik/whoAreWe.html
>
>
>Jeremias Maerki
>
>
>---------------------------------------------------------------------
>To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
>For additional commands, email: fop-dev-help@xml.apache.org
' Best,
-Ralph LaChance
In theory, there is no difference between
theory and practice, but in practice there is.
(Jan L.A. van de Snepsheut (1953-1994), late of CalTech)
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Project Team Page (WAS: release-website synchronization)
Posted by Victor Mote <vi...@outfitr.com>.
Victor Mote wrote:
> Unless there are objections, I'll go ahead and add this in a few days from
> the sources that we already have. Then each committer can add their own
> comments. I like the professionalism of the Batik page, and folks can add
> links to more extensive CV if they wish.
Hearing no objections, I have just committed a very minimal page with names
and email addresses of active committers, active contributors, and former
committers. This is a minefield, because I know, Know, KNOW that there are
others, especially in the "active contributors" category. Please make/submit
corrections if you can. Also, I didn't attempt to add any CV information or
list contributions, so please make those changes as well.
In fact, as I think about it, I see that I have missed the original
contributor entirely. I'll fix that here in a minute.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
RE: release-website synchronization
Posted by Victor Mote <vi...@outfitr.com>.
Jeremias Maerki wrote:
> While we're discussing the website:
> What would you think about a Who-we-are page like the one from Batik?
> http://xml.apache.org/batik/whoAreWe.html
+1
Unless there are objections, I'll go ahead and add this in a few days from
the sources that we already have. Then each committer can add their own
comments. I like the professionalism of the Batik page, and folks can add
links to more extensive CV if they wish.
Victor Mote
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org
Re: release-website synchronization
Posted by Jeremias Maerki <de...@greenmail.ch>.
On 13.05.2003 20:43:25 Victor Mote wrote:
> 1. Reflects current CVS.
> Pros: Keeps the flow of doc consistent with the flow of development.
> Cons: Requires either a general warning telling the user to look at
> distribution documentation instead of the website, or more specific comments
> within the content that say things like "PDF encryption support is available
> starting with 0.20.5".
+1
Only think about the current situation where some deficiencies are found.
You want them fixed as soon as possible.
Thanks for taking care of the comments.
While we're discussing the website:
What would you think about a Who-we-are page like the one from Batik?
http://xml.apache.org/batik/whoAreWe.html
Jeremias Maerki
---------------------------------------------------------------------
To unsubscribe, e-mail: fop-dev-unsubscribe@xml.apache.org
For additional commands, email: fop-dev-help@xml.apache.org