4 ms·

I think technical writing can be fun. Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tu

by wenc 8y ago

I think technical writing can be fun. Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. Most people who write computer books must surely enjoy technical writing to some extent. (Would love to hear what motivates O’Reilly authors, if there are any here) For me there’s something satisfying about writing something in Sphinx and seeing the beautiful final product on readthedocs.org. I’m also the sort of person who feels a sense of satisfaction seeing my writing end up in the form of aesthetically pleasing LaTeX output. Aesthetics is unrelated to the writing process, but oddly it does seem to provide motivation for it in my experience. Also, producing a piece of writing makes me feel like I’ve made a creative contribution to the world, however small.

taneq 8y ago
> Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. API documentation is one area that really, REALLY needs the latter kind of writing. There is far too much Doxygen-generated "documentation" which says things like "int foo(int power): Does 'foo' with power set to 'power' and returns the result."
- wenc 8y ago
  I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerical algorithms, I also embed math via LaTeX tags. Sphinx converts them to MathJax which renders the math quite nicely. The final output from Sphinx is beautiful (I use the Solar theme [1] for Sphinx). As long as I keep my docstrings up to date, the API documentation generates itself and does so beautifully. I’m sure something similar exists for other languages but I would agree with you that most Doxygen docs are mechanical and devoid of the human touch (most only contain method signatures and non descriptive comments if they exist at all). They are also aesthetically unpleasant which affects their usability, which in turn dampens devs’ motivation to document their code (“why document if the final output is ugly and no one looks at it?”). I wonder if a better theme would help. [1] theme preview here https://vimalkvn.github.io/solar-theme/ https://vimalkvn.github.io/solar-theme/
  - abathur 8y ago
    Mosra has put a lot of nice work into what is roughly a Doxygen theme (I'm not certain, but AFAIR it technically builds from the XML output and isn't a true drop-in replacement for the default theme), m.css, which you can see in action at https://doc.magnum.graphics/magnum/ https://doc.magnum.graphics/magnum/ and https://mcss.mosra.cz/doxygen/ https://mcss.mosra.cz/doxygen/ These demonstrate, I think, that Doxygen isn't irredeemable--but the exception does also highlight that the ecosystem has some tendencies that aren't great :)
- abathur 8y ago
  It does. I think you know this given how you phrased the last part, but I do want a mount a tiny defense of Doxygen, here: it's just as easy to write the same low-effort documentation in a simple comment, docstring, RST, markdown, docbook, latex, etc. I think it's often a symptom of things like: just trying to tick the box (i.e. doc-building rules that only include "documented" members, satisfy a doc linter/coverage tool), and being too close to the code to imagine what will and won't make sense to unfamiliar users.
  - taneq 8y ago
    Oh, absolutely. Doxygen is a good tool - possibly TOO good, because it allows lazy devs to produce something that looks like documentation with almost zero effort. There are plenty of other ways for them to achieve the same goal, though. I think your "trying to tick the box" cause is most likely, especially because that often results in "get the newbie to do it" or even "outsource it to India" where the person writing the docs has no idea what to write and so they just translate the function prototype into English. You can definitely also get it from being too close to the code (or to the problem domain) - I looked up the help for a form in my new accounting package and the help literally says "fill out the form"! Super helpful when populating columns like "Amount".

by wenc 8y ago

taneq 8y ago

> Not the kind of mundane technical writing where one is merely documenting APIs, but where one is explaining stuff in a tutorial-like fashion or writing about cool new features. API documentation is one area that really, REALLY needs the latter kind of writing. There is far too much Doxygen-generated "documentation" which says things like "int foo(int power): Does 'foo' with power set to 'power' and returns the result."

wenc 8y ago
I normally write API documentation as reStructuredText directly in Python docstrings which are then auto generated via Sphinx. Because I tend to write numerical algorithms, I also embed math via LaTeX tags. Sphinx converts them to MathJax which renders the math quite nicely. The final output from Sphinx is beautiful (I use the Solar theme [1] for Sphinx). As long as I keep my docstrings up to date, the API documentation generates itself and does so beautifully. I’m sure something similar exists for other languages but I would agree with you that most Doxygen docs are mechanical and devoid of the human touch (most only contain method signatures and non descriptive comments if they exist at all). They are also aesthetically unpleasant which affects their usability, which in turn dampens devs’ motivation to document their code (“why document if the final output is ugly and no one looks at it?”). I wonder if a better theme would help. [1] theme preview here https://vimalkvn.github.io/solar-theme/ https://vimalkvn.github.io/solar-theme/
- abathur 8y ago
  Mosra has put a lot of nice work into what is roughly a Doxygen theme (I'm not certain, but AFAIR it technically builds from the XML output and isn't a true drop-in replacement for the default theme), m.css, which you can see in action at https://doc.magnum.graphics/magnum/ https://doc.magnum.graphics/magnum/ and https://mcss.mosra.cz/doxygen/ https://mcss.mosra.cz/doxygen/ These demonstrate, I think, that Doxygen isn't irredeemable--but the exception does also highlight that the ecosystem has some tendencies that aren't great :)
abathur 8y ago
It does. I think you know this given how you phrased the last part, but I do want a mount a tiny defense of Doxygen, here: it's just as easy to write the same low-effort documentation in a simple comment, docstring, RST, markdown, docbook, latex, etc. I think it's often a symptom of things like: just trying to tick the box (i.e. doc-building rules that only include "documented" members, satisfy a doc linter/coverage tool), and being too close to the code to imagine what will and won't make sense to unfamiliar users.
- taneq 8y ago
  Oh, absolutely. Doxygen is a good tool - possibly TOO good, because it allows lazy devs to produce something that looks like documentation with almost zero effort. There are plenty of other ways for them to achieve the same goal, though. I think your "trying to tick the box" cause is most likely, especially because that often results in "get the newbie to do it" or even "outsource it to India" where the person writing the docs has no idea what to write and so they just translate the function prototype into English. You can definitely also get it from being too close to the code (or to the problem domain) - I looked up the help for a form in my new accounting package and the help literally says "fill out the form"! Super helpful when populating columns like "Amount".