Talk:Documentation generator

Untitled

I read an excellent article disparaging documentation generators not so long ago. However, I can no longer find it. It discussed how they fail to provide a proper high-level view of the code, discourage the writing of real documentation, and are easily surpassed as API documentation by a clear source (which includes the comments and docstrings anyway). Does anyone know the article I'm talking about? This is for personal interest, but such a viewpoint is probably also important for the article. --88.111.240.31 23:29, 22 January 2007 (UTC)

IMO that is not controversial. A human, technical writer can do a better job. But... not all technical writers have that level of skill. And, the main thing: who has technical writers anymore? ;) A generator allows for pretty good documentation in a way that doesn't add headcount; leveraging the need to document the code anyway (with comments in the code). In the old days, everyone had secretaries to do the typing. Today, everyone does their own typing. Is that better? IDK. But it's cheaper than hiring secretaries. Here's a note from Javadoc: Venners, Bill; Gosling, James; et al. (2003-07-08). "Visualizing with JavaDoc". artima.com. Retrieved 2013-01-19. When I did the original JavaDoc in the original compiler, even the people close around me pretty soundly criticized it. And it was interesting, because the usual criticism was: a good tech writer could do a lot better job than the JavaDoc does. And the answer is, well, yeah, but how many APIs are actually documented by good tech writers? And how many of them actually update their documentation often enough to be useful? Maybe you'd like to add this reference to this article. Honestly, I don't think it's all that important, but maybe you do. Stevebroshar (talk) 15:51, 8 January 2025 (UTC)