Standardize design documentation for plugin features

[ohltyler]

Opening this issue to discuss different options and agree upon a standard for plugins to follow.

Currently, not many detailed design docs for implemented features in plugins are checked into their respective repos. Some benefits of including these in the repos:

1. Increases community transparency regarding technical details of existing plugin features + upcoming features
2. Increases community involvement in the feature development lifecycle of large features
3. Can be referenced in relevant PRs to help provide context to the code changes

I propose to hold design reviews via opening & reviewing PRs that are checking in a design doc for a new feature. Discussion can take place on the PR itself, and when the feature is finalized, it can be checked into a docs/ directory in the plugin repo.

To handle the problem of docs becoming stale over time, the docs themselves can include links to the RFC for the feature, and the creation date.

Please add any thoughts / comments to this.

[saratvemulapalli]

Thanks @ohltyler for this. Love the idea.
Was just exploring better ways to represent design docs and found this: https://github.com/vitiral/artifact

[joshuali925]

Any guidance on this?

[ohltyler]

@saratvemulapalli what do you think about moving this to v1.1.0? I think this is kind of a larger and slower process in the change in where design doc discussions happen, rather than a concrete change that can happen by this release. Maybe have a concrete requirement to convert & merge main design docs into GitHub by 1.1?

[saratvemulapalli]

@saratvemulapalli what do you think about moving this to v1.1.0? I think this is kind of a larger and slower process in the change in where design doc discussions happen, rather than a concrete change that can happen by this release. Maybe have a concrete requirement to convert & merge main design docs into GitHub by 1.1?

+1 I agree, anyway we will not have any new designs for 1.0.0.

[ohltyler]

Cool. Please update #41 as well to remove that checkbox.

[saratvemulapalli]

@elfisher @ahopp @aetter any thoughts on this?

[elfisher]

I like this idea.

[dblock]

How do we move this forward?