DOC: Issue with the general expressiveness of the docs

[epigramx]

Pandas version checks

• I have checked that the issue still exists on the latest versions of the docs on main here

Location of the documentation

Example: https://pandas.pydata.org/docs/reference/api/pandas.Series.dt.floor.html

Documentation problem

Throughout the docs the explanation of a function is often limited only to a circular sentence that repeats the verb that names the function and nothing else. Eg in the example of pandas.Series.dt.floor it basically says "it does floor" and the details of the docs are restricted to the individual options and outcomes after that.

Suggested fix for documentation

In the example of floor it should first say in a richer sentence what floor actually does. It doesn't have to be anything big. I won't write an example of that because the docs didn't tell me what floor does.

[rhshadrach]

Thanks for the report.

is often limited only to a circular sentence that repeats the verb that names the function and nothing else

What should pandas say about sum? Should sum be explained as if the reader was unfamiliar with the mathematical operation? My answer here is no - this is okay to assume, and similarly for all standard operations. Of course one needs to decide what is "standard", and here there can be disagreements, but I would say the docs are okay to assume the reader is familiar with the floor operation. Descriptions of this are readily provided on searches for "floor operation" is users are not familiar.

That said, while I don't find this problematic I'm still open to improving the description if suggestions are provided. Marking this as Needs Info until that's provided.

[rhshadrach]

Ah, also I see now that this just used floor as an example. I think "docs can be improved by making them more expressive" is not a particularly useful issue to have open - it has no good closing criterion. Making it more focused on a function or a collection of related function all with similar issues would be more helpful I think.

[epigramx]

no - this is okay to assume, and similarly for all standard operations

Numpy documentation defines floor mathematically.

[mroeschke]

Thanks but agreed this issue is too nebulous to be actionable so closing. If you can identify specific parts of the documentation that need improvement with said improvement than feel free to open another issue