5 ms·

> With GitHub Pages, Read the Docs, and other places to host generated documentation for free > If your documentation is generated from source code, I am immed

> With GitHub Pages, Read the Docs, and other places to host generated documentation for free > If your documentation is generated from source code, I am immediately skeptical Looks like another self-important troll. Those statements are just lolwhut. I'm not going to learn (or force others to learn) a tool to read documentation. Put a /docs folder in the appropriate project directories and have the team that handles it, decide what to put in that (even if it's a URL to somewhere else). Disregarding existing documentation because you dislike the organization/formatting is such an act of blind ignorance, I'm surprised he thinks he knows anything about it. Documentation is not a solved problem (although it's easier than testing). > If you included all of the things needed to document a project in source, your code would be unreadable. That's only because modern IDEs haven't implemented inline-documentation methods yet. One day we'll get companion documents with every sourcefile that will allow developers to read notes and link to associated content from orthogonal comment files.

MrTonyD 8y ago
While I don't agree with the article 100%, I too am skeptical when I see documentation generated from source. A complex topic requires decomposing the information into different types of information with different approaches to explain it. Not everything is "here is the API". For example there may be an important overarching conceptual model, and information which maps into it. I don't know any way to express that in any of the source program documentation tools (at least, I've never seen it done in the many hundreds of projects I've seen.) The problems go well beyond formatting and organization. (Though, some things are simple APIs where some trivial examples and some minimal text can explain it sufficiently. That does describe a lot of existing libraries.)
- kevin_thibedeau 8y ago
  Sphinx does this better than most since it is a general purpose documentation tool first with API doc generation as an optional add on. After setting it up you can easily add manually written documentation as needed. Most importantly, you can easily cross-reference the API docs and the manual prose from each other. Doxygen and its ilk are overly focused on generated API documentation extracted from meta-comments and you rarely see them used with well organized manually written text.

MrTonyD 8y ago

While I don't agree with the article 100%, I too am skeptical when I see documentation generated from source. A complex topic requires decomposing the information into different types of information with different approaches to explain it. Not everything is "here is the API". For example there may be an important overarching conceptual model, and information which maps into it. I don't know any way to express that in any of the source program documentation tools (at least, I've never seen it done in the many hundreds of projects I've seen.) The problems go well beyond formatting and organization. (Though, some things are simple APIs where some trivial examples and some minimal text can explain it sufficiently. That does describe a lot of existing libraries.)

kevin_thibedeau 8y ago
Sphinx does this better than most since it is a general purpose documentation tool first with API doc generation as an optional add on. After setting it up you can easily add manually written documentation as needed. Most importantly, you can easily cross-reference the API docs and the manual prose from each other. Doxygen and its ilk are overly focused on generated API documentation extracted from meta-comments and you rarely see them used with well organized manually written text.