DEV Community

Discussion on: Don't Drown in Documentation

ikirker profile image
Ian Kirker • Edited on

It's been my experience that people are happy to dump information into a wiki but many will rarely, if ever, update it or clear out obsolete parts.

I'm not really sure what to do about this part short of trying to make it as easy and light-weight as possible to do, and I suspect (but haven't tested) that the best solution to this is wikis based on a VCS where the users can download all the files to their own system, and use their existing local file editing tools, rather than a web interface.

Confluence in particular seems very heavy to me since Atlassian removed the markup interface and made it all use the rich-text editor.

mathieuhalley profile image
Mathieu Halley

A process that could help with wiki-based documentation would be to have every single article on the wiki automatically marked as out of date on some regular schedule.
Active articles would quickly be edited and acknowledged as up to date, whereas abandoned articles would either be removed or left marked as out of date.

ikirker profile image
Ian Kirker

This sounds like a good idea, at least to start from.

I've also considered something like a bot that would give people "A Doc a Day" -- mailing people a single page that they can then either update, delete, or mark for a more involved look.