The psychology of writing documentation, why does it seem tedious?

Offtopic
1

Here is my theory.

When in a “programming” mindset, you can get near instant feedback. Either you get the correct result or not. Or the new version is more performant than the last.

But with the documentation there is no feedback on whether it is really helpful to include detail x in the summary, or related function y in the “See also”.

If there was a way to generate some kind of instant feedback, it could result in better docs.

Any ideas? Maybe checking what an LLM tries to do with the code? Or is there an example of a package with “ideal” docs?

3 Likes
2

This is not the question but another theory is that documentation is usually tedious because it’s just a sort of translation of the code itself, which is something not exciting in general

5 Likes
3

Not that I think it incorrect, but that theory is kind of defeatist.

In that case, the solution is to eventually automate it like we do for other tedious tasks. I assume that doesn’t work very well or everyone would be doing it though.

1 Like
4

yes, I mean I don’t want to sound too harsh, it happens in some cases that documentation is like that, but actually there can be joy in being able to pinpoint crucial factors or to explain the underlying implementation in simple words. And I’m referring to API docstrings here, documentation in the form of tutorials is generally cooler to write in my opinion.

5

When I write docs, I have an imaginary new user in my mind that is reading my work, and my “instant feedback” is my user becoming less and less confused.

I actually kinda think materializing that user with an LLM isn’t a terrible idea (and I have a bias to think that ideas which include LLMs are terrible :wink:).

4 Likes
6

I take the same stand, but while writing the docs I realize how much burden I put on the shoulders of the fictitious reader. And with a wave of empathy I start refactoring the software to make the story telling easier…

6 Likes
7

I just had a random idea that Ran LLM pretends to be a user and evaluates different versions of a document.

I’ve tried to refactor some of the documentation for math functions, but quickly found that it was a complex problem to determine what the documentation should contain.

Use sin as an example:

In other lang:

Maybe it would be enough to bring our documentation up to the level of SciPy’s doc or Matlab’s doc, and then draw some inspiration from wolfram’s documentation.

2 Likes
8

This does seem like one task where LLM-driven proofreading/suggestion workflows could be valuable.

9

I Iike it.

10

Yea, I haven’t yet found LLMs very helpful either. But it seems like a promising usecase.

11

I find LLMs write quite decent docstrings. Do others have a different experience?

12

Docstring experience for me is great on args/kwargs. But the actual description usually needs a lot of work. Nice to have a rough draft, but sometimes the ways it’s incorrect are subtle.

2 Likes