put example early on the page

[davidelang]

trafficstars

up at the very top of the page there should be an example of a trivial, common use case, so that people don't have to page down to find the examples (and since they aren't always the last thing, they can't just go to the end of the page)

[deoren]

@davidelang Would making sure to put the examples at the bottom of each page be an acceptable workaround?

If providing them early is still desired, would this example outline work?

1. Title
2. Brief summary
3. Examples
4. Parameters
   1. Module parameters
   2. Input (or Action) parameters
5. Feature details
6. Caveats / Known Bugs

Is this suggestion intended primarily for the module docs or any page where examples would prove useful?

[davidelang]

This is any pages where examples are useful.

it could be a link down to the examples.

my case was that I need to configure impstats but don't remember the exact syntax, so I google for the page, and what I need is the first, trivial example to remind me of the details, but I have to search for it.

this early example isn't a full, with details, it's just enough of a sample so someone who has an idea of what they are doing and knows what the module/whatever is can get a quick jumpstart with a 'hello world' type useage of the feature in question.

[deoren]

@davidelang Gotcha. That makes sense. I could see working in the most common, trivial use case directly at the end of each summary section as something that would be really useful.

[davidelang]

I could even see an argument for it being above the summary, especially if the summary is large.

the idea being that it should show up on the first screen of data, no matter what size screen you are using.

[deoren]

@davidelang: I could even see an argument for it being above the summary, especially if the summary is large.

the idea being that it should show up on the first screen of data, no matter what size screen you are using.

Understood. Re the summary though, it would probably be useful to have that be only a few sentences long (thinking of the module docs), then lead into the quick example. At some point on the page the longer description could be given where applicable (perhaps like the systemd section on the imuxsock doc).

[davidelang]

On Wed, 7 Mar 2018, Deoren Moor wrote:

Understood. Re the summary though, it would probably be useful to have that be only a few sentences long (thinking of the module docs), then lead into the quick example. At some point on the page the longer description could be given where applicable (perhaps like the systemd section on the imuxsock doc).

That makes sense, some of the 'summary' sections are quite long.

so executive summary hello world example more description of the module details of the parameters examples etc

[deoren]

Makes sense. This is good material for a docs "dev guide" if/when we get around to writing it (#451).