I'd like to propose the addition of a topic introduction or topic description area above the Examples in a topic and below the Topic title. When a user is creating a new topic they will not only title the topic but also provide an intro/description which can also be edited (like the topic title can be, from the same panel).
I've provided a mock-up of what the topic page would look like with the addition of an introduction/description section below the topic title but before the examples. See below:
When one thinks of documentation it is usually expected to be able to go to a topic and find a description or introduction to the specific topic and then more details/examples.
Currently in Documentation here on the SO beta, many topics dive right into examples with little to no introduction unless the author of the topic example decides to provide the information within their example. This distracts from the examples and makes the introduction/description seem out of place. I believe this is because there is no designated place or request for a topic introduction/description leaving authors no choice but to leave one out or add it into their example which may lead to multiple repeated descriptions of a topic.
Since most of us authoring these examples are already familiar with the topics we may overlook adding an intro or description within our example. For some of us that may be okay, but for users who will come to Documentation looking for a better understanding of a topic, or need a refresher on the topic before diving into examples, it may be confusing and inconvenient.
I believe that with this simple addition we can provide more information and context for the user regardless of their knowledge level on the topic when they are coming into the Documentation to look at examples.
edit: I'd like to add that I am aware of the Remarks
section within Documentation. Since there are users creating examples and using them to put an introduction for a topic rather than using the Remarks
area I believe this shows that it is rather unintuitive. On top of this, the Remarks
are all the way at the bottom of the topic page, which is out of the way. I also feel that the word Remark is probably not the best word to use if the intention is to "help readers better understand the examples for this topic." Perhaps another way to work this suggestion would be to rename Remarks
and move it higher on the page.
Remarks
section?Remarks
should be moved to the top or maybe be changed from being named Remarks to something else? When I seeRemarks
I think something that is just mentioned briefly rather than something I would go to to find detailed information. Might just be me though. :)