Re: documentation structure (was: attribute: add comments)

[Bruno Haible]

Hi Paul,

> I went through
> the comments and tweaked them in a way that I hope makes them even clearer.

In doing so, unfortunately, in several places you removed the first sentence,
which answered the question "What is its use-case?".

Generally, it's a good guideline to structure the technical documentation of
a feature or function in three parts:
  1. Why, when?
  2. What?
  3. How?
In detail:
  1. Answer the question "Why and under which conditions should I use XY?"
  2. Answer the question "What does XY do?"
  3. Answer the question "How do I use XY? What specific syntax do I have to
     use? What are the arguments that I have to pass?"

Many developers tend to write a documentation with 3. "How", or 3. "How"
and 2. "What" intermixed. This is not so good.

Part 1 is important so that people who look for something don't need to read
the entire description before noticing that this is not what they are looking
for. A single sentence should usually be sufficient for that.

Part 2 is for the user to understand the feature / function abstractly, so
that they can think about whether it really fits their use-case.

Part 3 then is for when they have decided that they want to use it, and need
a detailed hands-on description what they have to provide.

Let me try to reinstante the answer to 1. "Why, when", by grouping the macros
according to their use-case.

Hope this still fits your taste.


2020-05-10  Bruno Haible  <address@hidden>

        attribute: Clarify list of attributes.
        * lib/attribute.h: Reorder the list of attributes, and group them by
        purpose.