api-guidelines

api-guidelines copied to clipboard

Along with a summary of the discussion and perspectives so far for each.

:+1: For better discoverability.

Do you think maintaining a separate list of the issues with summaries would be better than a link to an issue filter with a summary maintained in the OP of each issue?

Great question. Yes in my opinion it would be better to have a curated appendix in the side bar with summaries. It can be scary to land on a long thread with dozens of multi-paragraph comments, even if the OP claims to summarize the ideas. I think a nice Markdown book page would be more accessible.

I would want the quality bar for these summaries to be similar to that for full-fledged guidelines. The difference would be that guidelines have a clear cut recommendation that we make to all crates, while these issues may be more nuanced where the best we can do is inform readers about the tradeoffs, why we hesitate to make a firm recommendation, and where they can go to argue about the merits of the alternatives.

The other piece of this is that as a discussion converges on a recommendation, it stops being a "soliciting opinions" issue and just becomes a normal issue to write a guideline. Just by being a "soliciting opinions" issue it means that there is no clear right answer yet, which is what this appendix would be for.