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!
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.
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
Cons
Prose/Wikis
Pros
Cons
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
How To Document A Kotlin Project
Casey Brooks ・ Feb 18 ・ 14 min read
What makes maintaining documentation difficult?
Casey Brooks ・ May 8 '18 ・ 1 min read
A beautiful and truly unique documentation engine and static site generator.
Orchid
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.
…