Skip to main content
Commonmark migration
Source Link

The most important, and only mandatory, set of pieces are Examples. Examples demonstrate how to use whatever is being documented and need to be self-contained (ideally copy/paste-able) and succinct.

 

Examples embody Show, Don’t Tell. A Topic will live and die by its Examples - a good Topic is one where most people don’t need to do anything beyond scan one of the Examples to find what they need to know.

The most important, and only mandatory, set of pieces are Examples. Examples demonstrate how to use whatever is being documented and need to be self-contained (ideally copy/paste-able) and succinct.

 

Examples embody Show, Don’t Tell. A Topic will live and die by its Examples - a good Topic is one where most people don’t need to do anything beyond scan one of the Examples to find what they need to know.

The most important, and only mandatory, set of pieces are Examples. Examples demonstrate how to use whatever is being documented and need to be self-contained (ideally copy/paste-able) and succinct.

Examples embody Show, Don’t Tell. A Topic will live and die by its Examples - a good Topic is one where most people don’t need to do anything beyond scan one of the Examples to find what they need to know.

replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
Source Link

So exactly what kind of documentationkind of documentation is this site for? If this site is for reference documentation, for documenting function calls, then why are they called "topics" and not "functions"? And why put the example first? Must functions that are complex enough to deserve reference documentation are too complex for one example to explain its full meaning. And having to sift through a half-dozen pieces of code before finding one that actually explain what it does is rather silly.

So exactly what kind of documentation is this site for? If this site is for reference documentation, for documenting function calls, then why are they called "topics" and not "functions"? And why put the example first? Must functions that are complex enough to deserve reference documentation are too complex for one example to explain its full meaning. And having to sift through a half-dozen pieces of code before finding one that actually explain what it does is rather silly.

So exactly what kind of documentation is this site for? If this site is for reference documentation, for documenting function calls, then why are they called "topics" and not "functions"? And why put the example first? Must functions that are complex enough to deserve reference documentation are too complex for one example to explain its full meaning. And having to sift through a half-dozen pieces of code before finding one that actually explain what it does is rather silly.

Rollback to Revision 2
Source Link
Nicol Bolas
  • 471.9k
  • 61
  • 186
  • 279

This is a documentation style that does not work for anything but the most basic of systems. This is a documentation style that does not work for anything but the most basic of systems.

This is a documentation style that does not work for anything but the most basic of systems.

This is a documentation style that does not work for anything but the most basic of systems.

highlighted for emphasis
Source Link
prusswan
  • 7.1k
  • 13
  • 10
Loading
added 4543 characters in body
Source Link
Nicol Bolas
  • 471.9k
  • 61
  • 186
  • 279
Loading
Source Link
Nicol Bolas
  • 471.9k
  • 61
  • 186
  • 279
Loading