To add a bit of color on the Falco Sandbox proposal and presentation. 

I started with the proposal document first because I felt that the problem we were trying to solve may not necessarily be well understood if we only did a presentation. I also wanted to have any of the questions/requirements for a Sandbox project answered ahead of the presentation. That way any TOC members could be confident that we met the requirements and we weren't wasting anyone's time. If questions or confusion came up, I had the proposal document to refer people back to. Lastly, I wanted people to clearly understand where we were fitting in the Cloud Native ecosystem, and the value we were providing. I felt like that would be harder to get across in the presentation. Personally, I felt that these were the barriers that we needed to overcome to get the TOC sponsors required. 

From the proposal I built the presentation, which felt like it naturally came out of the proposal. Each section became a slide (or two), and we had a much more clear story to tell on the slides as it was right there in the document as well. The proposal document also gave us a much more clear story to tell when we presented to the TOC.  

I'm not sure if most projects present first then write the proposal, but if not, it might be useful to flip it around. 

Michael

On Tue, Oct 2, 2018 at 12:10 PM Chris Aniszczyk <caniszczyk@...> wrote:

I agree requiring the writing up front (instead of after the presentation) can be useful, here are some good examples imho:

Falco (sandbox)

https://github.com/cncf/toc/pull/157

https://github.com/cncf/toc/blob/a9099dbc47d981339277cf813b0f1a0f052e52a5/proposals/falco.adoc

Rook (sandbox->incubation)

https://github.com/cncf/toc/pull/139

https://github.com/jbw976/toc/blob/1f622935ae334271458beafcc8a36a9ce13603a3/reviews/incubation-rook.md

If we want a specific template happy to hear ideas, we can put it in the TOC repo.

On Tue, Oct 2, 2018 at 11:06 AM Camille Fournier <skamille@...> wrote:

Chris pointed out in chat that groups already are writing up docs for their proposals. However, the problem in my mind is that first we see a slide deck style presentation, then it is followed by a written doc.

I can't speak for Bob, but as someone who heavily adopted Amazon-style paper writing over presentations for much of my internal team, I far prefer reading thoroughly-written docs to watching slide shows. Right now, the details that we get in a lot of the proposals we vote on are not nearly as thorough as what we see in the presentations, and if we tried to replace the presentations with the proposal docs, we would not have much to go on. 

A typical design doc that I would review would have information like:

Summary

Project goals (possibly including user scenarios this is aimed at addressing)

Project non-goals

High-level design

Roadmap

There's no one exact way to write one, but if we want to move to a writing-driven review process at least for sandbox projects, we should agree on more questions we want answered as part of the doc and length recommendations (and possibly restrictions). I feel like this doc is going to be a hybrid product/tech design doc, so if there are any product managers who want to chime in with further suggestions I'm all ears.

C

--

Chris Aniszczyk (@cra) | +1-512-961-6719