ditch inline documentation in favor of an external markdown-based documentation.

[v0lkan]

You can use a tool like

https://github.com/millermedeiros/mdoc

Over time I've seen that

• Inline docs are not adequate to show the full functionality of the codebase
• Or you have to provide a lot of @example pragmas to make the docs work
• And nobody (including contributor/developers) reads inline docs, they just read the generated documentation
• Inline docs makes the developers lazy, as in "I can write unreadable code, and document all the exceptional cases inside the jsdoc tags." -- documentation should be used to explain usage of the code; not the all the edge cases, internals, and the implementation details of the code (to get the details you read the source; not the docs)
• The best form of documentation is the source code itself
• Inline docs increase noise
• Tools like JS-doc and stuff are designed for object-oriented thinking; however JavaScript is much of a functional language, function is just a function, you should not have to think about which module/class/submodule it belongs to.
• No matter how hard you try, inline docs are not as flexible as creating a separate markdown page to document a functionality.

My inclination is to create a simple markdown documentation folder structure and see how it goes, and maybe use a tool (or write simple one myself) to create browsable HTML previews out of the markdown files.

[v0lkan]

I need to write a blog post about this too.

[gaboesquivel]

I agree with you the code should be self explanatory. thanks for the ref 👍

[v0lkan]

no worries, my pleasure.