You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general@incubator.apache.org by robert burrell donkin <ro...@gmail.com> on 2006/09/18 23:13:58 UTC
[doc] call for feedback for http://incubator.apache.org/guides/proposal.html
http://incubator.apache.org/guides/proposal.html is currently a
draft document. i think that it's strong enough to push towards
promoting it (and putting it in the indexes).
feedback would be very much appreciated. as always, if anyone can see
any improvements please post a patch to this list, open a JIRA or (if
you have karma) dive in.
but in particular please reply with feedback about:
1 presentation (is the way the content presented easily digested and
understandable?)
2 commentary (is the commentary on the template generally too long,
too short or just about right?)
3 examples (would more examples and/or long examples improve the
document or (conversely) are the examples too verbose at present?)
4 style changes (blue for notes)
cheers
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Dan Diephouse <da...@envoisolutions.com>.
This is very good Robert. Comments inline:
robert burrell donkin wrote:
> http://incubator.apache.org/guides/proposal.html is currently a
> draft document. i think that it's strong enough to push towards
> promoting it (and putting it in the indexes).
>
> feedback would be very much appreciated. as always, if anyone can see
> any improvements please post a patch to this list, open a JIRA or (if
> you have karma) dive in.
>
> but in particular please reply with feedback about:
>
> 1 presentation (is the way the content presented easily digested and
> understandable?)
Yup.
>
> 2 commentary (is the commentary on the template generally too long,
> too short or just about right?)
>
Seems just right to me.
> 3 examples (would more examples and/or long examples improve the
> document or (conversely) are the examples too verbose at present?)
>
The examples are very helpful. Definitely not too verbose!
> 4 style changes (blue for notes)
>
The styling makes it very clear whats an example and whats not. I like it.
Cheers,
- Dan
--
Dan Diephouse
(616) 971-2053
Envoi Solutions LLC
http://netzooid.com
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by robert burrell donkin <ro...@gmail.com>.
On 9/21/06, Leo Simons <ma...@leosimons.com> wrote:
<snip>
> Finally, perhaps the "background" section at the top could be
> expanded a little. Things one might spell out could be
>
> * proposals are not set in stone. Things can change later as the
> software evolves.
>
> * target audience. The "target", I guess, is not just the people
> doing voting, but also the people that might be helping out or using
> the software in the future. Proposals to the incubator do generate
> attention and they can be a good start to finding more people to work
> with.
added some comments to the background allow those lines
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Leo Simons <ma...@leosimons.com>.
On Sep 18, 2006, at 11:13 PM, robert burrell donkin wrote:
> http://incubator.apache.org/guides/proposal.html is currently a
> draft document. i think that it's strong enough to push towards
> promoting it (and putting it in the indexes).
+1. Good work.
> but in particular please reply with feedback about:
Besides "yes, put it live", its hard to come up with actually useful
comments...
> 1 presentation (is the way the content presented easily digested and
> understandable?)
To me, yes. But I'm not the best candidate. Ideally you'd want some
feedback from someone new to this incubation thing...hey you, list
lurker, speak up :-)
> 2 commentary (is the commentary on the template generally too long,
> too short or just about right?)
I think its good to keep the commentary reasonably short (like now).
People need to do their own thinking, and each proposal is unique.
> 3 examples (would more examples and/or long examples improve the
> document or (conversely) are the examples too verbose at present?)
I think there'll always be some information relevant about some
project that doesn't quite fit the template. That's the one example I
missed as being "explicit" (even though you mention the debate-y-
ness). If we have some reasonable example of a project where a non-
standard question was asked and answered maybe an excerpt of that
discussion could be included.
> 4 style changes (blue for notes)
*shrug*.
Finally, perhaps the "background" section at the top could be
expanded a little. Things one might spell out could be
* proposals are not set in stone. Things can change later as the
software evolves.
* target audience. The "target", I guess, is not just the people
doing voting, but also the people that might be helping out or using
the software in the future. Proposals to the incubator do generate
attention and they can be a good start to finding more people to work
with.
cheers,
Leo
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
On 9/20/06, robert burrell donkin <ro...@gmail.com> wrote:
> well spotted and a good point
>
> i've replaced the light blue with a navy and it looks fine on my LCD.
> once the site has sync'd take a look and see if the contrast is ok
> now.
Much better! Thanks. -- justin
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by robert burrell donkin <ro...@gmail.com>.
<snip>
On 9/19/06, Justin Erenkrantz <ju...@erenkrantz.com> wrote:
> The other thing that I would find helpful is to change the color of
> the examples and commentary. They are way too similar. Maybe one of
> them should be boxed with a dark-color background? It's a minor nit,
> but I think if we can make the distinction greater (the font
> difference isn't enough, IMO), it'd be easier to understand.
well spotted and a good point
i've replaced the light blue with a navy and it looks fine on my LCD.
once the site has sync'd take a look and see if the contrast is ok
now.
> (Actually, if I look at it, I think you may have tried with a
> light-blue and white? If so, the color difference is too subtle.)
(FWIW i lightened the border in a misguided attempt at subtlety...)
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by robert burrell donkin <ro...@gmail.com>.
On 9/20/06, Justin Erenkrantz <ju...@erenkrantz.com> wrote:
> On 9/20/06, robert burrell donkin <ro...@gmail.com> wrote:
> > i've had some negative comments about my obsession with TOCs in the
> > past but one is probably justified here. they are a PITA to maintain
> > so i'll probably add a new element to the generation template...
>
> =)
added toc element to the template which generates a table of contents.
added table of contents to proposal. take a look once it's sync'd.
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
On 9/20/06, robert burrell donkin <ro...@gmail.com> wrote:
> i've had some negative comments about my obsession with TOCs in the
> past but one is probably justified here. they are a PITA to maintain
> so i'll probably add a new element to the generation template...
=)
> i could also port the sitemap generation code i created for
> http://www.apache.org/dev/sitemap.html if there's a demand.
> opinions...?
Whatever you like. =) -- justin
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by robert burrell donkin <ro...@gmail.com>.
On 9/19/06, Matthieu Riou <ma...@gmail.com> wrote:
> It's really good, I like the template a lot. It will probably be very
> helpful. And I agree that a TOC would be helpful.
>
> On 9/19/06, Justin Erenkrantz <ju...@erenkrantz.com> wrote:
<snip>
> > First, what about a TOC at the beginning that links to the other
> > sections of the documents? That way people have an idea of the
> > sections - but this document is long enough that a TOC is nice to
> > have.
i've had some negative comments about my obsession with TOCs in the
past but one is probably justified here. they are a PITA to maintain
so i'll probably add a new element to the generation template...
i could also port the sitemap generation code i created for
http://www.apache.org/dev/sitemap.html if there's a demand.
opinions...?
- robert
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Matthieu Riou <ma...@gmail.com>.
It's really good, I like the template a lot. It will probably be very
helpful. And I agree that a TOC would be helpful.
On 9/19/06, Justin Erenkrantz <ju...@erenkrantz.com> wrote:
>
> On 9/18/06, robert burrell donkin <ro...@gmail.com> wrote:
> > http://incubator.apache.org/guides/proposal.html is currently a
> > draft document. i think that it's strong enough to push towards
> > promoting it (and putting it in the indexes).
>
> +1.
>
> > 1 presentation (is the way the content presented easily digested and
> > understandable?)
>
> Two small comments for your consideration.
>
> First, what about a TOC at the beginning that links to the other
> sections of the documents? That way people have an idea of the
> sections - but this document is long enough that a TOC is nice to
> have.
>
> The other thing that I would find helpful is to change the color of
> the examples and commentary. They are way too similar. Maybe one of
> them should be boxed with a dark-color background? It's a minor nit,
> but I think if we can make the distinction greater (the font
> difference isn't enough, IMO), it'd be easier to understand.
> (Actually, if I look at it, I think you may have tried with a
> light-blue and white? If so, the color difference is too subtle.)
>
> Even with these minor nits, this is certainly good enough to link from
> the main page. Thanks so much - this is going to be a great help! --
> justin
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
> For additional commands, e-mail: general-help@incubator.apache.org
>
>
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Justin Erenkrantz <ju...@erenkrantz.com>.
On 9/18/06, robert burrell donkin <ro...@gmail.com> wrote:
> http://incubator.apache.org/guides/proposal.html is currently a
> draft document. i think that it's strong enough to push towards
> promoting it (and putting it in the indexes).
+1.
> 1 presentation (is the way the content presented easily digested and
> understandable?)
Two small comments for your consideration.
First, what about a TOC at the beginning that links to the other
sections of the documents? That way people have an idea of the
sections - but this document is long enough that a TOC is nice to
have.
The other thing that I would find helpful is to change the color of
the examples and commentary. They are way too similar. Maybe one of
them should be boxed with a dark-color background? It's a minor nit,
but I think if we can make the distinction greater (the font
difference isn't enough, IMO), it'd be easier to understand.
(Actually, if I look at it, I think you may have tried with a
light-blue and white? If so, the color difference is too subtle.)
Even with these minor nits, this is certainly good enough to link from
the main page. Thanks so much - this is going to be a great help! --
justin
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org
Re: [doc] call for feedback for http://incubator.apache.org/guides/proposal.html
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
On 9/18/06, robert burrell donkin <ro...@gmail.com> wrote:
> http://incubator.apache.org/guides/proposal.html is currently a
> draft document. i think that it's strong enough to push towards
> promoting it (and putting it in the indexes).
+1 to marking it as a non-draft document, it seems quite reasonable to
me, and nothing jumped out as requiring changes.
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: general-unsubscribe@incubator.apache.org
For additional commands, e-mail: general-help@incubator.apache.org