Comment by amingilani | Hacker News Reader

Comment by amingilani | Hacker News Reader

Here's a summary:

1. Get a website: don't use a readme on GitHub.

2. Use Prose: don't generate from source, you need more.

3. Give permalinks for citation purposes

4. Your URL should acknowledge the documentation version and language, for future-proofing

And now for my own opinion:

1. No, not every project finds it rational to put time into creating a website. Especially if they're small. Sometimes, the time is better spent doing dev work than creating a pretty site to satisfy you.

2. Rails' documentation is generated from source, so is Node's. A lot of documentation is. They give accompanying guides, sure, but there's nothing wrong with generating the majority of your documentation from source.

3 & 4. These are nice to have, sure, but not requirements. If a project is small, I'd rather the solo dev spend their free time solving tough problems.

Essentially: if you're judging a whole project in 30 seconds, I think you're the problem and not the developer that spent all their time making a project for you to use. So, go ahead, "close the tab" as many times as you like there. But if you really want to help someone, open a pull request, or at least file an issue in a curteous time.

Disagree on the readme.md. At work, we recently moved away from dedicated project/component documentation pages and toward readme.md.

It's the best way to ensure that the documentation is in sync with the implementation: the developer is more likely to update the readme.md in the same pull request he/she changes the implementation.

On Github, I seldom read the market-y website. I click the "Fork me on Github" link and go to the documentation pages on the source itself. It's the most reliable, in my view.

Likewise, I always consult the GitHub docs (usually README.md) and code rather than see the website (which is sometimes out of sync) but usually projects which do not have a dedicated website do not have good READMEs either. This is my experience with full-stack JavaScript libraries/plugins.

Also helps when you have to work offline.

I work on projects while I travel, and I always force my package manager to download the source (not dist) version of the package.

The readme files are now included in the project, and it's a lot easier to just read them. Add an MD viewer to the IDE to make things easier.

You really have to go out of your way to not provide 3., any half-decent documentation generation mechanism, even trivial markdown rendering scripts, will have some sort of support for permalinks.

Short of deliberately not versioning your documentation, it's quite difficult to avoid producing working permalinks.

Generating reference from source is fine, but it's definitely insufficient. Trying to pick up a library or a framework from reference alone is like learning a language solely from a dictionary. Documentation should at least include some general design and architecture elements, and tutorials or commented examples.

Writing accurate documentation mostly requires a thorough understanding of the code, it's one of the least easy things to contribute productively as a newcomer.

I'd much rather the developer did not implement some features (which they took the time to list or maybe even sketch out their intentions for in the documentation), and documented what they did implement thoroughly. That's a much better starting point for contribution than a more or less feature-complete project that needs reverse engineering because there is no documentation at all.

> 2. Rails' documentation is generated from source, so is Node's. A lot of documentation is.

I don't think that's the problem he is talking about. Whether you put your prose in a separate file or as a special comment in a source file is not a relevant difference. Having prose, and having a sensible TOC, is.

Broadly speaking, generated docs tend to be worthless for smaller, well-designed packages, i.e. those where you can browse and read the code+comments in your IDE comfortably. But large and poorly designed packages definitely need generated docs, because their code isn't easily traversed.

Basically I think generated references are a necessary evil. If your project needs them I think that's a wrinkle on the project.

I'm struck by how contradictory the author's guidelines seem to be. If your documentation lives in source code and github readmes, then bam! - you automatically have permalinks to everything that are intrinsically synced to the version of the code. If you keep your docs in separate files on a separate website, you get those things iff you remember to manually generate them.

One example of when generating from source can make for a less than ideal experience is the Monaco editor's documentation[0].

- Most modules don't have intro sections to guide you to where you might want to start looking for the most common tasks. You have to guess the kinds of names they might have chosen for the given tasks. Turns out customizing syntax highlighting is mainly done with setMonarchTokensProvider and not setTokensProvider.

- Many methods or classes have redundant docstrings, like how setLanguageConfiguration[1] says "Set the editing configuration for a language" or setTheme() says "Switches to a theme."

- To find out what you can do with instances of a code editor, you don't click "monaco.editor" in the right sidebar like I kept thinking. Instead, you'd click the create() method on that page, and click through to its return type, which is actually IStandaloneCodeEditor.

- The search field only searches on exact prefixes of the basename. This isn't exactly a generate-from-code problem but a typedoc UI issue that led me to just download the code and use search-in-project instead (within VS Code ironically enough).

Fortunately, for the most common tasks, the Monaco playground[2] and Monarch playground[3] were helpful in pointing me to the right direction. So that offsets some of these annoyances. But I actually switched away from generating bland documentation via typeoc for my app, and started using a custom documentation generator that allows me to structure my app's docs in a way that is more human-friendly.

[0] https://microsoft.github.io/monaco-editor/api/index.html

[1] https://microsoft.github.io/monaco-editor/api/modules/monaco...

[2] https://microsoft.github.io/monaco-editor/playground.html

[3] https://microsoft.github.io/monaco-editor/monarch.html

Node.js actually has separate docs[1]. The only documentation you'll find inline in our source is documentation for other developers working on the source.

[1]: https://github.com/nodejs/node/tree/master/doc/api

> Rails' documentation is generated from source, so is Node's.

Indeed! There's no better documentation than the code itself.

Godoc —the documentation tool for Go— also generates it from the source code.

Concise and clear, here is an example input [1] and its corresponding output [2].

[1] https://golang.org/src/net/http/doc.go

[2] https://golang.org/pkg/net/http/

Indeed! There's no better documentation than the code itself.

Except for all the things you need to know in order to use the code. Which are why you still write actual real honest-to-God prose documentation. Or, if you don't, is why I don't bother trying to use your code.

If you read the links given, you'll see that is in the godoc. Godoc has a place to put prose documentation. The formatting is quite weak (you get headers of more than one word, paragraphs of text without italic or bold but with URLs turned into active links, etc, and preformatted-code), but it's often enough. (If it really isn't enough, link somewhere.) Godoc also has official support for examples, which are included in the documentation and tested as part of the automated test suite, ensuring they stay up to date if written even halfway reasonably.

This is not specific to godoc. Most, perhaps effectively all (certainly all the ones I've seen and used), automated code generation tools have a place to put arbitrary prose at the top. The fact that it is so often unused is a developer problem, not a tool problem.

Reply on news.ycombinator.com