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

**URL:** <https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429>\
**Category:** Offtopic\
**Tags:** documentation\
**Created:** [December 3, 2024, 10:48pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429 "2024-12-03T22:48:51Z")\
**Posts on this page:** 12\
**Page:** 1

<div class="post-metadata">

**Author:** ![Tetrakai](https://avatars.discourse-cdn.com/v4/letter/t/4da419/32.png) [@Tetrakai](https://discourse.julialang.org/u/Tetrakai)\
**Post date:** [December 3, 2024, 10:48pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/1 "2024-12-03T22:48:51Z")

</div>

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?

---

<div class="post-metadata">

**Author:** ![Tortar](https://avatars.discourse-cdn.com/v4/letter/t/6bbea6/32.png) [@Tortar](https://discourse.julialang.org/u/Tortar)\
**Post date:** [December 3, 2024, 10:53pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/2 "2024-12-03T22:53:09Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![Tetrakai](https://avatars.discourse-cdn.com/v4/letter/t/4da419/32.png) [@Tetrakai](https://discourse.julialang.org/u/Tetrakai)\
**Post date:** [December 3, 2024, 11:18pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/3 "2024-12-03T23:18:43Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![Tortar](https://avatars.discourse-cdn.com/v4/letter/t/6bbea6/32.png) [@Tortar](https://discourse.julialang.org/u/Tortar)\
**Post date:** [December 3, 2024, 11:54pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/4 "2024-12-03T23:54:52Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [December 4, 2024, 2:47am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/5 "2024-12-04T02:47:42Z")

</div>

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 😉).

---

<div class="post-metadata">

**Author:** ![laborg](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/laborg/32/5474_2.png) [@laborg](https://discourse.julialang.org/u/laborg)\
**Post date:** [December 4, 2024, 4:16am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/6 "2024-12-04T04:16:11Z")

</div>

> [@mrufsvold](#):
>
> 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 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…

---

<div class="post-metadata">

**Author:** ![woclass](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/woclass/32/212699_2.png) [@woclass](https://discourse.julialang.org/u/woclass)\
**Post date:** [December 4, 2024, 4:23am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/7 "2024-12-04T04:23:59Z")

</div>

> [@Tetrakai](#):
>
> If there was a way to generate some kind of instant feedback, it could result in better docs.

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:

- [sin - Mathematics · The Julia Language](https://docs.julialang.org/en/v1/base/math/#Base.sin-Tuple%7BNumber%7D)  
Base version
- [sin · The Missing Doc 4 Julia](https://cyhan.dev/TheMissingDoc4Julia.jl/dev/ElementaryMath/Trigonometry/Sine/sin/)  
Does this page of documentation provide the necessary information? Or does it contain too much useless content?

In other lang:

- [numpy.sin — NumPy v2.1 Manual](https://numpy.org/doc/stable/reference/generated/numpy.sin.html)
- [sin - matlab](https://www.mathworks.com/help/matlab/ref/double.sin.html?s_tid=doc_ta)
- [Sin: Get the sine of an expression—Wolfram Documentation](https://reference.wolfram.com/language/ref/Sin.html)

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.

---

<div class="post-metadata">

**Author:** ![tecosaur](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tecosaur/32/23206_2.png) [@tecosaur](https://discourse.julialang.org/u/tecosaur)\
**Post date:** [December 4, 2024, 9:00am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/8 "2024-12-04T09:00:46Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![lmiq](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/lmiq/32/18314_2.png) [@lmiq](https://discourse.julialang.org/u/lmiq)\
**Post date:** [December 4, 2024, 9:15am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/9 "2024-12-04T09:15:23Z")

</div>

> [@woclass](#):
>
> Does this page of documentation provide the necessary information? Or does it contain too much useless content?

I Iike it.

---

<div class="post-metadata">

**Author:** ![Tetrakai](https://avatars.discourse-cdn.com/v4/letter/t/4da419/32.png) [@Tetrakai](https://discourse.julialang.org/u/Tetrakai)\
**Post date:** [December 4, 2024, 6:14pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/10 "2024-12-04T18:14:09Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![simsurace](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/simsurace/32/30216_2.png) [@simsurace](https://discourse.julialang.org/u/simsurace)\
**Post date:** [December 4, 2024, 6:31pm UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/11 "2024-12-04T18:31:09Z")

</div>

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

---

<div class="post-metadata">

**Author:** ![mrufsvold](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/mrufsvold/32/31600_2.png) [@mrufsvold](https://discourse.julialang.org/u/mrufsvold)\
**Post date:** [December 5, 2024, 12:18am UTC](https://discourse.julialang.org/t/the-psychology-of-writing-documentation-why-does-it-seem-tedious/123429/12 "2024-12-05T00:18:55Z")

</div>

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.