I document extensively with JSDoc and Visual Studio's default C# document style. But I don't (yet) write anything to an external wiki.

I find it useful to describe classes' and methods' intended role in the larger business context. I think that sometimes carries meaning that the code alone cannot.

I'm all for self explaining code and long, declarative function names. However I see them more fitting for describing "what" the code does and rather limited for "why". Whenever I try to adopt third party code I find it much more challenging to understand the architecture than the methods.

I just included wikis for the sake of completeness. I had to document in confluence in the past and found it very problematic. It kept being forgotten, out of date and cumbersome. No recommendation from me.

I find that both doc-blocks in your code and wiki-style prose documentation are very useful, and for larger projects, both are absolutely needed.

I completely agree that wikis kept in another repository or in an external system are extremely prone to getting out of sync, which is why I prefer to keep wikis as Markdown inside the project repo itself. Even putting a fair amount of structured prose in a README is a great idea, too, if you don't need a full multi-page wiki. And as a bonus, you get versioned documentation for free simply by tagging your releases!

Here's my pro/con list for both doc-blocks and wikis:

Doc-blocks

Pros

• For advanced users of your project, or someone looking to contribute to it
• Good for understanding the individual code elements (class relationships, available methods, etc)
• Allows users to get an understanding of a library from intellisense popups in their IDE, so they don't have to refer to your docs site for everything

Cons

• Not great for new users, hard for them to know where to start or it's core feature-set
• Makes code cluttered, harder to scan
• No direction, hard to know where to go to continue learning about the project
• Prone to copy/paste errors, doesn't get refactored with the code and can fall out-of-sync if not careful

Prose/Wikis

Pros

• Great for onboarding new users
• Has a clear entry point, with clear direction to more advanced topics
• Only general concepts and core features belong in a wiki. But these shouldn't change much in a mature project, so it gives a good overview of what a project is there for.
• Documents the "happy path" of your code: the way it's intended to be used

Cons

• If kept in another repository, it's prone to falling out of sync quickly
• If kept inside the project repository, you'll end up with a messy commit history, containing both code and docs changes
• Can be difficult to publish (need to generate the docs site, push to Github Pages, etc.)
• More likely to grow stale, since you aren't looking at the wiki pages all the time

As the maintainer of a documentation tool, Orchid, I've posted here several times related to documentation. Check them out for more of my thoughts on documentation, and try Orchid as a solution to the normal cons of a wiki!

5 Tips for Writing Good Documentation

Casey Brooks ・ Nov 5 '18 ・ 1 min read

#documentation #opensource #orchid

How To Document A Kotlin Project

Casey Brooks ・ Feb 18 ・ 14 min read

#kotlin #documentation #orchid

What makes maintaining documentation difficult?

Casey Brooks ・ May 8 '18 ・ 1 min read

#discuss