[discuss] replacing SPIP template with Heilmeier's Catechism?

[Reynold Xin <rx...@databricks.com>]

I helped craft the current SPIP template
<https://spark.apache.org/improvement-proposals.html> last year. I was
recently (re-)introduced to the Heilmeier Catechism, a set of questions
DARPA developed to evaluate proposals. The set of questions are:

- What are you trying to do? Articulate your objectives using absolutely no
jargon.
- How is it done today, and what are the limits of current practice?
- What is new in your approach and why do you think it will be successful?
- Who cares? If you are successful, what difference will it make?
- What are the risks?
- How much will it cost?
- How long will it take?
- What are the mid-term and final “exams” to check for success?

When I read the above list, it resonates really well because they are
almost always the same set of questions I ask myself and others before I
decide whether something is worth doing. In some ways, our SPIP template
tries to capture some of these (e.g. target persona), but are not as
explicit and well articulated.

What do people think about replacing the current SPIP template with the
above?

At a high level, I think the Heilmeier's Catechism emphasizes less about
the "how", and more the "why" and "what", which is what I'd argue SPIPs
should be about. The hows should be left in design docs for larger projects.

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Sean Owen <sr...@apache.org>]

Looks good. From the existing template at
https://spark.apache.org/improvement-proposals.html I might keep points
about design sketch, API, and non goals. And we don't need a cost section.

On Fri, Aug 31, 2018, 1:23 PM Reynold Xin <rx...@databricks.com> wrote:

> I helped craft the current SPIP template
> <https://spark.apache.org/improvement-proposals.html> last year. I was
> recently (re-)introduced to the Heilmeier Catechism, a set of questions
> DARPA developed to evaluate proposals. The set of questions are:
>
> - What are you trying to do? Articulate your objectives using absolutely
> no jargon.
> - How is it done today, and what are the limits of current practice?
> - What is new in your approach and why do you think it will be successful?
> - Who cares? If you are successful, what difference will it make?
> - What are the risks?
> - How much will it cost?
> - How long will it take?
> - What are the mid-term and final “exams” to check for success?
>
> When I read the above list, it resonates really well because they are
> almost always the same set of questions I ask myself and others before I
> decide whether something is worth doing. In some ways, our SPIP template
> tries to capture some of these (e.g. target persona), but are not as
> explicit and well articulated.
>
> What do people think about replacing the current SPIP template with the
> above?
>
> At a high level, I think the Heilmeier's Catechism emphasizes less about
> the "how", and more the "why" and "what", which is what I'd argue SPIPs
> should be about. The hows should be left in design docs for larger projects.
>
>
>

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Matei Zaharia <ma...@gmail.com>]

I like this as well. Regarding “cost”, I think the equivalent concept for us is impact on the rest of the project (say maintenance cost down the line or whatever). This could be captured in the “risks” too, but it’s a slightly different concept. We should probably just clarify what we mean with each question.

Matei

> On Aug 31, 2018, at 1:09 PM, Cody Koeninger <co...@koeninger.org> wrote:
> 
> +1 to Sean's comment
> 
> On Fri, Aug 31, 2018 at 2:48 PM, Reynold Xin <rx...@databricks.com> wrote:
>> Yup all good points. One way I've done it in the past is to have an appendix
>> section for design sketch, as an expansion to the question "- What is new in
>> your approach and why do you think it will be successful?"
>> 
>> On Fri, Aug 31, 2018 at 12:47 PM Marcelo Vanzin
>> <va...@cloudera.com.invalid> wrote:
>>> 
>>> I like the questions (aside maybe from the cost one which perhaps does
>>> not matter much here), especially since they encourage explaining
>>> things in a more plain language than generally used by specs.
>>> 
>>> But I don't think we can ignore design aspects; it's been my
>>> observation that a good portion of SPIPs, when proposed, already have
>>> at the very least some sort of implementation (even if it's a barely
>>> working p.o.c.), so it would also be good to have that information up
>>> front if it's available.
>>> 
>>> (So I guess I'm just repeating Sean's reply.)
>>> 
>>> On Fri, Aug 31, 2018 at 11:23 AM Reynold Xin <rx...@databricks.com> wrote:
>>>> 
>>>> I helped craft the current SPIP template last year. I was recently
>>>> (re-)introduced to the Heilmeier Catechism, a set of questions DARPA
>>>> developed to evaluate proposals. The set of questions are:
>>>> 
>>>> - What are you trying to do? Articulate your objectives using absolutely
>>>> no jargon.
>>>> - How is it done today, and what are the limits of current practice?
>>>> - What is new in your approach and why do you think it will be
>>>> successful?
>>>> - Who cares? If you are successful, what difference will it make?
>>>> - What are the risks?
>>>> - How much will it cost?
>>>> - How long will it take?
>>>> - What are the mid-term and final “exams” to check for success?
>>>> 
>>>> When I read the above list, it resonates really well because they are
>>>> almost always the same set of questions I ask myself and others before I
>>>> decide whether something is worth doing. In some ways, our SPIP template
>>>> tries to capture some of these (e.g. target persona), but are not as
>>>> explicit and well articulated.
>>>> 
>>>> What do people think about replacing the current SPIP template with the
>>>> above?
>>>> 
>>>> At a high level, I think the Heilmeier's Catechism emphasizes less about
>>>> the "how", and more the "why" and "what", which is what I'd argue SPIPs
>>>> should be about. The hows should be left in design docs for larger projects.
>>>> 
>>>> 
>>> 
>>> 
>>> --
>>> Marcelo
>>> 
>>> ---------------------------------------------------------------------
>>> To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
>>> 
>> 
> 
> ---------------------------------------------------------------------
> To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
> 


---------------------------------------------------------------------
To unsubscribe e-mail: dev-unsubscribe@spark.apache.org

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Cody Koeninger <co...@koeninger.org>]

+1 to Sean's comment

On Fri, Aug 31, 2018 at 2:48 PM, Reynold Xin <rx...@databricks.com> wrote:
> Yup all good points. One way I've done it in the past is to have an appendix
> section for design sketch, as an expansion to the question "- What is new in
> your approach and why do you think it will be successful?"
>
> On Fri, Aug 31, 2018 at 12:47 PM Marcelo Vanzin
> <va...@cloudera.com.invalid> wrote:
>>
>> I like the questions (aside maybe from the cost one which perhaps does
>> not matter much here), especially since they encourage explaining
>> things in a more plain language than generally used by specs.
>>
>> But I don't think we can ignore design aspects; it's been my
>> observation that a good portion of SPIPs, when proposed, already have
>> at the very least some sort of implementation (even if it's a barely
>> working p.o.c.), so it would also be good to have that information up
>> front if it's available.
>>
>> (So I guess I'm just repeating Sean's reply.)
>>
>> On Fri, Aug 31, 2018 at 11:23 AM Reynold Xin <rx...@databricks.com> wrote:
>> >
>> > I helped craft the current SPIP template last year. I was recently
>> > (re-)introduced to the Heilmeier Catechism, a set of questions DARPA
>> > developed to evaluate proposals. The set of questions are:
>> >
>> > - What are you trying to do? Articulate your objectives using absolutely
>> > no jargon.
>> > - How is it done today, and what are the limits of current practice?
>> > - What is new in your approach and why do you think it will be
>> > successful?
>> > - Who cares? If you are successful, what difference will it make?
>> > - What are the risks?
>> > - How much will it cost?
>> > - How long will it take?
>> > - What are the mid-term and final “exams” to check for success?
>> >
>> > When I read the above list, it resonates really well because they are
>> > almost always the same set of questions I ask myself and others before I
>> > decide whether something is worth doing. In some ways, our SPIP template
>> > tries to capture some of these (e.g. target persona), but are not as
>> > explicit and well articulated.
>> >
>> > What do people think about replacing the current SPIP template with the
>> > above?
>> >
>> > At a high level, I think the Heilmeier's Catechism emphasizes less about
>> > the "how", and more the "why" and "what", which is what I'd argue SPIPs
>> > should be about. The hows should be left in design docs for larger projects.
>> >
>> >
>>
>>
>> --
>> Marcelo
>>
>> ---------------------------------------------------------------------
>> To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
>>
>

---------------------------------------------------------------------
To unsubscribe e-mail: dev-unsubscribe@spark.apache.org

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Reynold Xin <rx...@databricks.com>]

Yup all good points. One way I've done it in the past is to have an
appendix section for design sketch, as an expansion to the question "- What
is new in your approach and why do you think it will be successful?"

On Fri, Aug 31, 2018 at 12:47 PM Marcelo Vanzin <va...@cloudera.com.invalid>
wrote:

> I like the questions (aside maybe from the cost one which perhaps does
> not matter much here), especially since they encourage explaining
> things in a more plain language than generally used by specs.
>
> But I don't think we can ignore design aspects; it's been my
> observation that a good portion of SPIPs, when proposed, already have
> at the very least some sort of implementation (even if it's a barely
> working p.o.c.), so it would also be good to have that information up
> front if it's available.
>
> (So I guess I'm just repeating Sean's reply.)
>
> On Fri, Aug 31, 2018 at 11:23 AM Reynold Xin <rx...@databricks.com> wrote:
> >
> > I helped craft the current SPIP template last year. I was recently
> (re-)introduced to the Heilmeier Catechism, a set of questions DARPA
> developed to evaluate proposals. The set of questions are:
> >
> > - What are you trying to do? Articulate your objectives using absolutely
> no jargon.
> > - How is it done today, and what are the limits of current practice?
> > - What is new in your approach and why do you think it will be
> successful?
> > - Who cares? If you are successful, what difference will it make?
> > - What are the risks?
> > - How much will it cost?
> > - How long will it take?
> > - What are the mid-term and final “exams” to check for success?
> >
> > When I read the above list, it resonates really well because they are
> almost always the same set of questions I ask myself and others before I
> decide whether something is worth doing. In some ways, our SPIP template
> tries to capture some of these (e.g. target persona), but are not as
> explicit and well articulated.
> >
> > What do people think about replacing the current SPIP template with the
> above?
> >
> > At a high level, I think the Heilmeier's Catechism emphasizes less about
> the "how", and more the "why" and "what", which is what I'd argue SPIPs
> should be about. The hows should be left in design docs for larger projects.
> >
> >
>
>
> --
> Marcelo
>
> ---------------------------------------------------------------------
> To unsubscribe e-mail: dev-unsubscribe@spark.apache.org
>
>

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Marcelo Vanzin <va...@cloudera.com.INVALID>]

I like the questions (aside maybe from the cost one which perhaps does
not matter much here), especially since they encourage explaining
things in a more plain language than generally used by specs.

But I don't think we can ignore design aspects; it's been my
observation that a good portion of SPIPs, when proposed, already have
at the very least some sort of implementation (even if it's a barely
working p.o.c.), so it would also be good to have that information up
front if it's available.

(So I guess I'm just repeating Sean's reply.)

On Fri, Aug 31, 2018 at 11:23 AM Reynold Xin <rx...@databricks.com> wrote:
>
> I helped craft the current SPIP template last year. I was recently (re-)introduced to the Heilmeier Catechism, a set of questions DARPA developed to evaluate proposals. The set of questions are:
>
> - What are you trying to do? Articulate your objectives using absolutely no jargon.
> - How is it done today, and what are the limits of current practice?
> - What is new in your approach and why do you think it will be successful?
> - Who cares? If you are successful, what difference will it make?
> - What are the risks?
> - How much will it cost?
> - How long will it take?
> - What are the mid-term and final “exams” to check for success?
>
> When I read the above list, it resonates really well because they are almost always the same set of questions I ask myself and others before I decide whether something is worth doing. In some ways, our SPIP template tries to capture some of these (e.g. target persona), but are not as explicit and well articulated.
>
> What do people think about replacing the current SPIP template with the above?
>
> At a high level, I think the Heilmeier's Catechism emphasizes less about the "how", and more the "why" and "what", which is what I'd argue SPIPs should be about. The hows should be left in design docs for larger projects.
>
>


-- 
Marcelo

---------------------------------------------------------------------
To unsubscribe e-mail: dev-unsubscribe@spark.apache.org

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Reynold Xin <rx...@databricks.com>]

I incorporated the feedbacks here and updated the SPIP page:
https://github.com/apache/spark-website/pull/156

The new version is live now:
https://spark.apache.org/improvement-proposals.html


On Fri, Aug 31, 2018 at 4:35 PM Ryan Blue <rb...@netflix.com> wrote:

> +1
>
> I think this is a great suggestion. I agree a bit with Sean, but I think
> it is really about mapping these questions into some of the existing
> structure. These are a great way to think about projects, but they're
> general and it would help to rephrase them for a software project, like
> Matei's comment on considering cost. Similarly, we might rephrase
> objectives to be goals/non-goals and add something to highlight that we
> expect absolutely no Jargon. A design sketch is needed to argue how long it
> will take, what is new, and why it would be successful; adding these
> questions will help people understand how to go from that design sketch to
> an argument for that design. I think these will guide people to write
> proposals that is persuasive and well-formed.
>
> rb
>
> On Fri, Aug 31, 2018 at 4:17 PM Jules Damji <dm...@comcast.net> wrote:
>
>> +1
>>
>> One could argue that the litany of the questions are really a
>> double-click on the essence: why, what, how. The three interrogatives ought
>> to be the essence and distillation of any proposal or technical exposition.
>>
>> Cheers
>> Jules
>>
>> Sent from my iPhone
>> Pardon the dumb thumb typos :)
>>
>> On Aug 31, 2018, at 11:23 AM, Reynold Xin <rx...@databricks.com> wrote:
>>
>> I helped craft the current SPIP template
>> <https://spark.apache.org/improvement-proposals.html> last year. I was
>> recently (re-)introduced to the Heilmeier Catechism, a set of questions
>> DARPA developed to evaluate proposals. The set of questions are:
>>
>> - What are you trying to do? Articulate your objectives using absolutely
>> no jargon.
>> - How is it done today, and what are the limits of current practice?
>> - What is new in your approach and why do you think it will be successful?
>> - Who cares? If you are successful, what difference will it make?
>> - What are the risks?
>> - How much will it cost?
>> - How long will it take?
>> - What are the mid-term and final “exams” to check for success?
>>
>> When I read the above list, it resonates really well because they are
>> almost always the same set of questions I ask myself and others before I
>> decide whether something is worth doing. In some ways, our SPIP template
>> tries to capture some of these (e.g. target persona), but are not as
>> explicit and well articulated.
>>
>> What do people think about replacing the current SPIP template with the
>> above?
>>
>> At a high level, I think the Heilmeier's Catechism emphasizes less about
>> the "how", and more the "why" and "what", which is what I'd argue SPIPs
>> should be about. The hows should be left in design docs for larger projects.
>>
>>
>>
>
> --
> Ryan Blue
> Software Engineer
> Netflix
>

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Ryan Blue <rb...@netflix.com.INVALID>]

+1

I think this is a great suggestion. I agree a bit with Sean, but I think it
is really about mapping these questions into some of the existing
structure. These are a great way to think about projects, but they're
general and it would help to rephrase them for a software project, like
Matei's comment on considering cost. Similarly, we might rephrase
objectives to be goals/non-goals and add something to highlight that we
expect absolutely no Jargon. A design sketch is needed to argue how long it
will take, what is new, and why it would be successful; adding these
questions will help people understand how to go from that design sketch to
an argument for that design. I think these will guide people to write
proposals that is persuasive and well-formed.

rb

On Fri, Aug 31, 2018 at 4:17 PM Jules Damji <dm...@comcast.net> wrote:

> +1
>
> One could argue that the litany of the questions are really a double-click
> on the essence: why, what, how. The three interrogatives ought to be the
> essence and distillation of any proposal or technical exposition.
>
> Cheers
> Jules
>
> Sent from my iPhone
> Pardon the dumb thumb typos :)
>
> On Aug 31, 2018, at 11:23 AM, Reynold Xin <rx...@databricks.com> wrote:
>
> I helped craft the current SPIP template
> <https://spark.apache.org/improvement-proposals.html> last year. I was
> recently (re-)introduced to the Heilmeier Catechism, a set of questions
> DARPA developed to evaluate proposals. The set of questions are:
>
> - What are you trying to do? Articulate your objectives using absolutely
> no jargon.
> - How is it done today, and what are the limits of current practice?
> - What is new in your approach and why do you think it will be successful?
> - Who cares? If you are successful, what difference will it make?
> - What are the risks?
> - How much will it cost?
> - How long will it take?
> - What are the mid-term and final “exams” to check for success?
>
> When I read the above list, it resonates really well because they are
> almost always the same set of questions I ask myself and others before I
> decide whether something is worth doing. In some ways, our SPIP template
> tries to capture some of these (e.g. target persona), but are not as
> explicit and well articulated.
>
> What do people think about replacing the current SPIP template with the
> above?
>
> At a high level, I think the Heilmeier's Catechism emphasizes less about
> the "how", and more the "why" and "what", which is what I'd argue SPIPs
> should be about. The hows should be left in design docs for larger projects.
>
>
>

-- 
Ryan Blue
Software Engineer
Netflix

Re: [discuss] replacing SPIP template with Heilmeier's Catechism?

[Jules Damji <dm...@comcast.net>]

+1 

One could argue that the litany of the questions are really a double-click on the essence: why, what, how. The three interrogatives ought to be the essence and distillation of any proposal or technical exposition.

Cheers
Jules 

Sent from my iPhone
Pardon the dumb thumb typos :)

> On Aug 31, 2018, at 11:23 AM, Reynold Xin <rx...@databricks.com> wrote:
> 
> I helped craft the current SPIP template last year. I was recently (re-)introduced to the Heilmeier Catechism, a set of questions DARPA developed to evaluate proposals. The set of questions are:
> 
> - What are you trying to do? Articulate your objectives using absolutely no jargon.
> - How is it done today, and what are the limits of current practice?
> - What is new in your approach and why do you think it will be successful?
> - Who cares? If you are successful, what difference will it make?
> - What are the risks?
> - How much will it cost?
> - How long will it take?
> - What are the mid-term and final “exams” to check for success?
> 
> When I read the above list, it resonates really well because they are almost always the same set of questions I ask myself and others before I decide whether something is worth doing. In some ways, our SPIP template tries to capture some of these (e.g. target persona), but are not as explicit and well articulated. 
> 
> What do people think about replacing the current SPIP template with the above? 
> 
> At a high level, I think the Heilmeier's Catechism emphasizes less about the "how", and more the "why" and "what", which is what I'd argue SPIPs should be about. The hows should be left in design docs for larger projects.
> 
>