5 ms·

Can you talk about the format of this doc? I did some googling but came up with nothing / a bunch of fluff pieces.

by idoh 9y ago

eigen-vector 9y ago
There's no format as it is; whatever suits the occasion I guess. If you're presenting an engineering design, it is expected that your document conveys the what, the why, and the how—ideally many hows along with pros and cons for each. A good narrative would be data-driven, and not riddled with intangibles.
- idoh 9y ago
  Ah OK. Basically, a written doc with sentences and paragraphs as opposed to a PPT or outline with bullet points then?
  - eigen-vector 9y ago
    That's more or less it. There are training sessions you can take where people who are good writers, teach you how to be a better writer. And the meetings, since they revolve around the narratives, involve getting constructive feedback on your writing besides simply getting feedback on your design.
  - andrewguenther 9y ago
    Yes
blasdel 9y ago
A common format is posed as a "Press Release" for the idea as if it existed, with quotes from customers — even if it's purely an internal service, the downstream teams are your customers The documents are fixed length to 1, 2, or 6 pages for different purposes/stages, and reference data goes in appendices that don't count. It's also impossible to be hired as a senior contributor or any management role without submitting a writing sample, which gets reviewed in the hiring meeting along with everyone's interview feedback.
- shostack 9y ago
  While I agree written communication skills are critical for senior roles, do you ever find this format stifling for more visual ideas and concepts? Or are designs and comps just included in the appendix with a couple embedded highlight images?
  - xzel 9y ago
    They're either embedded in the text or as an appendix. Its not really a hard fast 6 pages exactly thing, more of a guideline. You want it to have depth but not be too long. Thats pretty much it. For more details: I'd say 1 pager is an idea. 2 pager is idea with the why and some details fleshed out. 6 pager is idea, why/how/people, design docs, stats/analysis and maybe even some tech choices. I thought it was a good model look into and plan projects. IMO, programming should be / is only 20-30% of a softdev's job, the rest should be planning (and probably fixing bugs afterwards haha). Source: Former Amazon dev.
  - gregdunn 9y ago
    I don't - there are plenty of ways to get visual ideas/concepts into the document. You can refer them to the appendix or embed it in. Appendixes are often quite large on complex topics. The big benefit is that meetings start with people reading the documents and thinking about them - you'll see people making notes in the margins, etc. Only after everyone has had a chance to read the doc do you start discussing it, so you save a lot of time answering questions that are answered in the doc.

Can you talk about the format of this doc? I did some googling but came up with nothing / a bunch of fluff pieces.

by idoh 9y ago

Can you talk about the format of this doc? I did some googling but came up with nothing / a bunch of fluff pieces.

There's no format as it is; whatever suits the occasion I guess. If you're presenting an engineering design, it is expected that your document conveys the what, the why, and the how—ideally many hows along with pros and cons for each. A good narrative would be data-driven, and not riddled with intangibles.

idoh 9y ago
Ah OK. Basically, a written doc with sentences and paragraphs as opposed to a PPT or outline with bullet points then?
- eigen-vector 9y ago
  That's more or less it. There are training sessions you can take where people who are good writers, teach you how to be a better writer. And the meetings, since they revolve around the narratives, involve getting constructive feedback on your writing besides simply getting feedback on your design.
- andrewguenther 9y ago
  Yes

blasdel 9y ago

A common format is posed as a "Press Release" for the idea as if it existed, with quotes from customers — even if it's purely an internal service, the downstream teams are your customers The documents are fixed length to 1, 2, or 6 pages for different purposes/stages, and reference data goes in appendices that don't count. It's also impossible to be hired as a senior contributor or any management role without submitting a writing sample, which gets reviewed in the hiring meeting along with everyone's interview feedback.

shostack 9y ago
While I agree written communication skills are critical for senior roles, do you ever find this format stifling for more visual ideas and concepts? Or are designs and comps just included in the appendix with a couple embedded highlight images?
- xzel 9y ago
  They're either embedded in the text or as an appendix. Its not really a hard fast 6 pages exactly thing, more of a guideline. You want it to have depth but not be too long. Thats pretty much it. For more details: I'd say 1 pager is an idea. 2 pager is idea with the why and some details fleshed out. 6 pager is idea, why/how/people, design docs, stats/analysis and maybe even some tech choices. I thought it was a good model look into and plan projects. IMO, programming should be / is only 20-30% of a softdev's job, the rest should be planning (and probably fixing bugs afterwards haha). Source: Former Amazon dev.
- gregdunn 9y ago
  I don't - there are plenty of ways to get visual ideas/concepts into the document. You can refer them to the appendix or embed it in. Appendixes are often quite large on complex topics. The big benefit is that meetings start with people reading the documents and thinking about them - you'll see people making notes in the margins, etc. Only after everyone has had a chance to read the doc do you start discussing it, so you save a lot of time answering questions that are answered in the doc.