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

classic Classic list List threaded Threaded
9 messages Options
Reply | Threaded
Open this post in threaded view
|

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

rxin
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.


Reply | Threaded
Open this post in threaded view
|

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

Sean Owen-3
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 <[hidden email]> 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.


Reply | Threaded
Open this post in threaded view
|

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

Marcelo Vanzin-2
In reply to this post by rxin
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 <[hidden email]> 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: [hidden email]

Reply | Threaded
Open this post in threaded view
|

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

rxin
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 <[hidden email]> 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 <[hidden email]> 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: [hidden email]

Reply | Threaded
Open this post in threaded view
|

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

Cody Koeninger-2
+1 to Sean's comment

On Fri, Aug 31, 2018 at 2:48 PM, Reynold Xin <[hidden email]> 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
> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>
>

---------------------------------------------------------------------
To unsubscribe e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

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

Matei Zaharia
Administrator
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 <[hidden email]> wrote:
>
> +1 to Sean's comment
>
> On Fri, Aug 31, 2018 at 2:48 PM, Reynold Xin <[hidden email]> 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
>> <[hidden email]> 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 <[hidden email]> 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: [hidden email]
>>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe e-mail: [hidden email]
>


---------------------------------------------------------------------
To unsubscribe e-mail: [hidden email]

Reply | Threaded
Open this post in threaded view
|

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

Jules Damji-2
In reply to this post by rxin
+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 <[hidden email]> 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.


Reply | Threaded
Open this post in threaded view
|

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

Ryan Blue
+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 <[hidden email]> 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 <[hidden email]> 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.




--
Ryan Blue
Software Engineer
Netflix
Reply | Threaded
Open this post in threaded view
|

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

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



On Fri, Aug 31, 2018 at 4:35 PM Ryan Blue <[hidden email]> 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 <[hidden email]> 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 <[hidden email]> 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.




--
Ryan Blue
Software Engineer
Netflix