Comment by bluGill
4 days ago
Both are needed for good documentation. You start with the details and then finish with a few examples so that someone who has read the details can check their understanding. Sometimes the example is all you need, but most often there are far more possible combinations of options such that an example of all the useful ones would be several books long (there is no good way to sort/index them so someone wouldn't find the example they need if you wrote them all). So you start with an explanation of each option, and then a few examples that are as different as you can make them so readers get a sense of what is possible and can look back to the explanation to figure out the changes they need to get the example to do what they need.
Good documentation is hard, and very rare these days.
Documentation is like the system it supports too: the only unchanging ones are those nobody is using! I think this is obvious when we compare quality between the historically much slow manual releases with the cadence today, and the documentation of relatively slowly changing projects with newer, faster ones. It's a lot of work to create good documentation; it's even more work to keep it good.