I don't think this is limited to docstrings. What makes you think so?

Fair, reading it again I can see how it has more general tips than I originally thought, though maybe not necessarily relevant for all types of documentation.

I think the problem may better be described as: it seems very prescriptive, i.e., too specific in detailing exactly what to include and the order, e.g.

1. hand-waving explanation
2. why method is useful and when it should be used
3. figure
4. code examples
5. math and equations

This may not be so relevant for all types of documentation, e.g., docstrings don't usually contain figures.

I think this issue should be more - make the guide more general for all types of documentation and suggest what could be included in various types of documentation (instead of suggesting that all types of documentation should include all 5 items), but I am also happy to close this issue as this is not as much of a problem as I originally thought.

closing this as it seems the docstring section has been updated and the above guidelines is specified for the user guide, which makes sense.