What constitutes the best documentation ?

Maciek

An offspring discussion from this thread.

@ManAtWork said:

@evanh said:
Regarding smartpin counter mode P_EVENTS_TICKS (%10010). The two sub-modes Y=0 vs Y=1 are dramatically different modes. I don't know why Chip stuck them together like that.

It's not only the ordering of the modes and sub modes... Every document so far only repeats Chip's descriptions. But honestly, I don't understand them at all. I mean I understand all the other smart pin modes but not the ones that measure time or count events. The descriptions explain what they physically do but I don't see any reason, intention or purpose in them.

IMHO, a clear documentation should explain it the other way round: Say, I want to measure a) duty cycle or b) measure frequency or c) phase relation. What mode should I use and how should I setup the registers? I don't like having to read all the docs and then guess which mode fits best what I need to do.

Hmm, that would be welcome and time saving, but might not be sufficient and does not extend beyound the main intended use case(s).

I, for one, would like to see good quality doccumentation to (in an order of importance):

1. accurately describe the matter (a feature, a subject or an instruction) - what it does and how exactly it does what it does
2. describe the specifics (like for example physical properties, timings, schematic etc)
3. describe the limitations
4. describe what the intended use is and how to properly set it up for such use
5. provide some basic but working examples with detailed explanations
6. give some hints on a possible use cases other than the main, most prominent one
7. keep the documentation up to date (periodic or on demand update with major changes)
8. encourage user's feedback on the documentation and provide means for it.