How do you document code?

Today I got into a discussion with a colleague on how to document code within a large web project. My preferred method is to trust my code to be self-explaining on what it does and rely on JSDocs or block comments for why it does its thing. Hacky or weird lines get the occasional line comment.
I dislike documenting my code in other places (like wikis or tickets), because that gets outdated and forgotten pretty quickly.

How do you handle that?
Do you trust your code to be self-explaining? Do you use JSDocs/PHPDocs/etc? Do you comment extensively? Or maintain a huge wiki?
What works out for you and why?

Comments

[Michael Crenshaw]

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.

[Daniel Schulz]

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.

[Casey Brooks]

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

JavaEden / Orchid

A beautiful and truly unique documentation engine and static site generator.

Orchid

A beautiful and truly unique documentation engine and static site generator.

Orchid is a brand-new, general-purpose static site generator for Java and Kotlin, with a focus on extensibility and aimed at developers looking to improve their technical documentation. Orchid was born out of a desire for better-looking Javadocs and frustration with how difficult is it to manage large Jekyll sites and keep it up-to-date with your code.

Orchid supports a variety of plugins, including a wiki, static pages, blogs, and much more. It aims to have high compatibility with many of the existing static site generators, such as Jekyll, Gitbook, and Hugo, so that migration to Orchid is painless. And if you can't find a plugin to do what you need, Orchid provides an intuitive way to add your own private plugins and a rich API so you can make your site as beautiful and unique as an Orchid.

…

View on GitHub