Comment by MrTonyD | Hacker News Reader

Comment by MrTonyD | Hacker News Reader

Interesting to see how someone experienced evaluates documentation. I've been doing Curriculum Development for several years, and it's easy to identify bad Curriculum. If I flip through a course and don't see a lot of diagrams (20%-50%) then I know that somebody didn't know all the research showing that diagrams aid recall and simplify the understanding of relationships. And if I don't see frequent labs/practice, then somebody didn't know all the research showing that the brain needs to have new concepts reinforced, and skipping that step prevents new information from being well-absorbed. I could go on, but those two are typical. And people wonder why Training isn't more effective. I have seen bad training sink more than one high-tech company - though nobody at those companies seemed to understand that. There is also an art to properly decomposing complex topics so that they can be "intuitive". My very best technical courses were often criticized as being "easy" and "obvious" - but only by those who hadn't tried to learn the same information before.

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

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

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.

Reply on news.ycombinator.com