Comment by massysett | Hacker News Reader

Comment by massysett | Hacker News Reader

"If your documentation is a directory full of files on GitHub, I close the tab."

Without even stopping to see if there is an INDEX or README that gives the files a hierarchy? Without considering whether those files are well-written? Without remembering that plain text files are portable, easy to author in many tools, and easy to view on many devices? You'd rather see a glitzy website with no content?

"If your documentation is generated from source code, I am immediately skeptical."

Even though keeping documentation with the code it documents makes it more likely the two will be in sync? Even though some library authors use their source code documentation tool to write entire files that are nothing but documentation? Maybe you're viewing it wrong: my documentation is not generated from source code. My documentation includes the source code and will generate the library.

Since he seems bent on judging things in 30 seconds I guess it is inevitable that he will elevate form over substance.

Sure, keep the files as plain text in the repo, I'm all for that. Just don't make it the main interface for viewing them. You are really arguing that a GitHub file browser is the best UX for viewing documentation?

Sure, keep documentation about code in the source code. Where exactly in the source code does your tutorial go?

You seem to be reading into a lot of things that aren't in the article based on what you want to hear.

less(1)

vi(1)

emacs(1)

firefox(1)

google-chrome(1)

Microsoft Word or Internet Explorer, if that's your thing!

As for "where does your tutorial go," see for example "Control.Pipes.Tutorial".

http://hackage.haskell.org/package/pipes-4.0.0/docs/Pipes-Tu...

If someone can't figure these things out, by all means, go use someone else's library. This sort of documentation would not be acceptable for a consumer product like TurboTax, but a programmer needs to know how to view a text file.

I know how to view a text file, or even navigate a directory of them. But as forsaken said, a GitHub file browser is often not the best UI for viewing documentation, especially when you're already in a browser.

What's better, the docs for Backbone.Marionette[0], or Backbone[1]?

[0]: https://github.com/marionettejs/backbone.marionette/tree/mas... [1]: http://backbonejs.org/

> What's better, the docs for Backbone.Marionette, or Backbone?

Offline or online viewing? Should I need a web connection to read the documentation?

Form follows function, to be sure, but form also follows function. That is, if you don't have function, one way to tell is a lack of form.

It's not always true, but it's an indication of a lack of function, improper form.

To me it's more common that elaborate form covers up lack of function.

What's important is writing an understandable library. Documentation cannot paper over a bad design. If it takes a ream of documentation to document something, sometimes the time spent on the docs would have been better spent writing a cleaner interface.

And simple documentation is in proper form. I'd rather spend time writing documentation than learning some new gee-whiz framework for writing documentation. Even time spent putting together a website is time that could have been spent writing documentation.

Another advantage of in-tree documentation is that the docs come with the code. When there's a separate website, you have to consult this separate place. Someone else in this thread pointed out that sometimes you can't get docs for an old version. Not a problem when the docs are in the VCS along with the rest of the code.

Reply on news.ycombinator.com