4 ms·

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 pu

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.

achamayou 8y ago
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.
guessmyname 8y ago
> 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 https://golang.org/src/net/http/doc.go [2] https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/
- ubernostrum 8y ago
  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.
  - jerf 8y ago
    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.
blattimwind 8y ago
> 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.
snek 8y ago
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 https://github.com/nodejs/node/tree/master/doc/api
sdegutis 8y ago
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 https://microsoft.github.io/monaco-editor/api/index.html [1] https://microsoft.github.io/monaco-editor/api/modules/monaco.languages.html#setlanguageconfiguration https://microsoft.github.io/monaco-editor/api/modules/monaco... [2] https://microsoft.github.io/monaco-editor/playground.html https://microsoft.github.io/monaco-editor/playground.html [3] https://microsoft.github.io/monaco-editor/monarch.html https://microsoft.github.io/monaco-editor/monarch.html
hliyan 8y ago
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.
- namanyayg 8y ago
  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.
  - Ayesh 8y ago
    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.
fenomas 8y ago
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.

achamayou 8y ago

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.

guessmyname 8y ago

> 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 https://golang.org/src/net/http/doc.go [2] https://golang.org/pkg/net/http/ https://golang.org/pkg/net/http/

ubernostrum 8y ago
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.
- jerf 8y ago
  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.

blattimwind 8y ago

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

snek 8y ago

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 https://github.com/nodejs/node/tree/master/doc/api

sdegutis 8y ago

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 https://microsoft.github.io/monaco-editor/api/index.html [1] https://microsoft.github.io/monaco-editor/api/modules/monaco.languages.html#setlanguageconfiguration https://microsoft.github.io/monaco-editor/api/modules/monaco... [2] https://microsoft.github.io/monaco-editor/playground.html https://microsoft.github.io/monaco-editor/playground.html [3] https://microsoft.github.io/monaco-editor/monarch.html https://microsoft.github.io/monaco-editor/monarch.html

hliyan 8y ago

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.

namanyayg 8y ago
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.
- Ayesh 8y ago
  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.

fenomas 8y ago

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.