Developer Documentation: Goodbye Wiki. Hello MkDocs!

TL;DR: A migration project is underway to bring wiki content into the Developer Guide.

The wiki is kind of like that drawer in your kitchen where you put things that seem useful but don't really have "a place". And it works okay, especially when its your kitchen, because you have a decent idea of what you've chucked in there over the years.

Hi my name is Sean and I'm an aspiring CiviCRM developer. After many years as a CiviCRM user and administrator, I've carved out some time in my life to effectively "go to school" on CiviCRM development. Last month, I got started by diving into reading the wiki, hoping it would serve as my text book. But instead I found someone else's kitchen drawer filled with – useful things, for sure – but also that familiar medley of old business cards, and grocery lists, and dull pencils, and oh god, what the…?!

Then on Mattermost I happened to see a link pointing to a new source of information – The Developer Guide. (Cue majestic choral harmonies.) Much cleaner, more usable, and current! But… woefully incomplete. Turns out it was only recently created, and hasn't gotten much love. But for many reasons people seem to agree that it's way better than the wiki because it's built with MkDocs. So for the past several weeks I've been working hard to pull the good stuff out of the wiki and into the Developer Guide. I've created detailed plans for a migration project, to be completed by May 1st, 2017. Part of the project thus far has included listing out all the 315 wiki pages underneath "Develop" and holding each one to see if it brings joy. Pages that make the cut get migrated to the Dev Guide, often with the help of a new import tool, and then a nifty system now creates redirects within the wiki pointing to each imported page when published in the Dev Guide. That means that when you reach in the kitchen drawer to find a rubber band, you'll be magically transported to "rubber band world" and see a selection of rubber bands, sorted by size and elasticity… well, eventually. There's still a lot of work to do.

This is where you come in! So far it's pretty much just me and Erich Schulz picking our way through the pearls of wisdom that are semi-organized. But because we're both new, we really could use some help! We have some open questions and would love your opinion. We have lots of pages to evaluate, and migrate. We are tracking issues and welcome additions. We also hang out in the Documentation channel and will answer your questions.

After this migration project is completed, we'll have a nice polished Developer Guide – just the text book I've always wanted! And the wiki will still exist too – most likely as that same kitchen drawer that we all love and hate, teetering on the boundary between order and chaos – but no longer burdened with the expectation of preserving important things like our kitchen cutlery. It will be a great place to share specifications and post "recipes" for how to accomplish specific (uncommon) tasks. The Developer Guide, conversely, will be the go-to source for clean, organized, comprehensive, up-to-date developer documentation – just like the User Guide has become for users. And from my personal experience, I can say this step will go a long way towards empowering new developers and building a more welcoming community!