search

FullFact / .github

Organisation-wide GitHub defaults, including issue templates
0 stars 0 forks source link

On enhancement tickets, split the ‘overview’ section into ‘Executive summary’ and ‘Details’ #3

Open andylolz opened 11 months ago

andylolz commented 11 months ago

Executive summary

A short summary expanding on the issue title would be helpful, distinct from the full details.

Details

The instructions for the current ‘Overview’ section say:

<!--
  Give a high level overview and background of the feature,
  explaining why it is needed or what it enables. There should
  be enough detail for someone to pick up this ticket and
  understand the reason for the new feature and how it might
  be used by users. Who? What? Why?
-->

I think these instructions are good, but could maybe be split into two sections:

  1. “a high level overview and background of the feature, explaining why it is needed or what it enables”. This could be the ‘executive summary’
  2. “enough detail for someone to pick up this ticket and understand the reason for the new feature and how it might be used by users. Who? What? Why?” This could be called ‘details’.