Design RFC template for docs projects

[jseldess]

Similar to how engineers write RFCs to plan the design and implementation of new features, I'd like to experiment with an RFC process for documentation projects, where writers would thoroughly think through the documentation implications of new features. This would let us do some of the hard initial planning/strategy ahead of time while features are in development. Importantly, it would also give us time/headspace to get proper input/feedback/collaboration from Product and Engineering.

First step is to design a Docs RFC template. See the Engineering RFC template for inspiration: https://github.com/cockroachdb/cockroach/blob/master/docs/RFCS/00000000_template.md

[jseldess]

cc: @Amruta-Ranade, @sploiselle, @nstewart, @bdarnell, in case you have ideas, but it's also fine to wait until I draft the initial template.

[jseldess]

Sidenote: Note sure if these documents need to live in the docs repo or just be, say, Google Docs. Also, don't think these need to be "announced" publicly like eng RFCs are. Though it would be wonderful to get input from the community, I wouldn't want to cramp the existing RFC workflow.

[sploiselle]

+1 This is an amazing idea.

A quick reason why I support this: for the architecture docs, I had a clear vision of what I thought the form of them would be, which I hadn't communicated clearly to anyone. When I realized that my stakeholders weren't aware of what exactly I was doing, I created a pseudo-RFC, got feedback on the structure (rather than solely the content itself), and ended up producing something that was drastically different––and better––than what I'd originally imagined.

I've alternatively heard these called "doc plans," but I think that approaching it from the engineering side of things is much better. Doc plans––in my experience––can get roadblocked on a lot of bureaucratic approval, but a "request for comment," means that we're inviting feedback rather than requiring it.

Weed-y Details

My one suggestion for this would be that each thing you plan to write clearly expresses what the purpose of the document is from the user's perspective. This could easily follow the ISBAT format, but it could also be anything else and achieve the same purpose.

I think this achieves some really great stuff:

• The writer has to clearly understand the outcome of the document, rather than just a topic they're writing about; this process also gives the writer a chance to find gaps in their coverage
• Users read docs to accomplish something; this ensures that the writer keeps that in mind
• Stakeholders/readers of the RFC have a clear idea why you're writing what you're writing. This lets them both feel at ease, as well as find possible gaps in coverage

If you were to do this for all of the content you planned to write, these things can easily be translated into the first sentence of each article, which means it's not only good "meta work,"
but it also provides kindling for the writing itself.

[jseldess]

Excellent input, @sploiselle. Thank you.

[Amruta-Ranade]

I love this idea!

I see two benefits of implementing this:

• In the Admin UI team meetings, we have been talking about "showing our work" to customers. And I have been wondering if I can adopt the concept for my doc tasks. I think an RFC would be the perfect instrument for that.
• I have also been thinking about ways to get feedback earlier and share document design decisions along the way with the stakeholders, instead of after writing the complete document. Because by the time I write the complete document, I might lose track of the rationale for the decisions. The RFC would be the perfect place to discuss the progress of the document and not just the final version.

I am all for it!

[jseldess]

I've been thinking about this further, in the context of the company-wide review of our current engineering RFC process. My feeling now is that an official RFC process for docs is too much. For large projects, some type of plan is important, however. We'll discuss at our next team meeting.