Back to Blog
Feb 4th, 2014

The Collaboration Machine of the Docs World

The Collaboration Machine of the Docs World

We all love and depend on open source software.

But what about open source content?

Open Source Software and tools like GitHub let us work together brilliantly. The result is huge gains in quality and innovation. That's really important.

But content - the documentation, tutorials and books that teach us about all of this tech - is behind the curve. Yes, official documentation is usually on a GitHub repository and we see a huge community effort with the Symfony documentation (nod to @WouterJ - pronounced Wow!ter). Even StackOverflow is an example of crowd-sourcing the information-side of tech. But mostly, books, blog posts and everything in between are still written by one person. They sit, slowly rot with time, and are eventually forgotten. New books are written by new authors from scratch. The cycle continues. We're all part of it.

This cycle is an antique. And like most things that move slowly, the Internet will correct this. Imagine a world where tutorials are based on real, high-quality projects written by many people and evolving over time. That's where I want to be.

Making Content Editable

More and more blogs are using GitHub-backed repositories, and although there isn't a culture (yet) of contributing like we do to code, I think it's inevitable.

Our screencast and blog content is also open source and lives up on GitHub. That's actually not new, but the "Edit" button at the top of this page and the contributors on the right is new. Get your avatar up there and push the culture of docs contributing by PR'ing some content. I even left a typo in this paragraph (though there's probably more on the page). Find it!

Reading from the Shoulders of Giants

Often there are topics I need to learn and a person that I know could build a perfect tutorial to teach me. For that reason, I've started humbly asking really smart (and busy) people to help write future tutorials: they bring expertise, we hopefully help with a lot of the not-so-fun work (writing, editing, video recording, etc).

We're starting by (being really lucky to) collaborate with some brilliant people:

And if you're great at something and I haven't already bothered you - ping us on Twitter or comment here. I want to bother you :).

Why Don't we all Write More?

If the problem is ultimately that we should all write more (and collaborate), then why don't we? What stops us from writing the tutorials we wish existed? I'd genuinely like to hear from you (again, comments!).

Here are some reasons I think, which could be totally wrong:

  • There's nowhere easy to publish it (this is not true for everyone);

  • It's way more fun to just write code;

  • There's nobody coordinating collaboration;

  • A tutorial and its code are disconnected - I need to write an app and then go back and document the steps. I'll have to copy code into the tutorial, which may be wrong or get outdated.

Right? Wrong? What stops you from writing a tutorial?

Code collaboration blew up when GitHub made the process easy and rewarding. I hope we can help do the same for tutorials... and include everyone on the process.

<3 Ryan


Sort By
Login or Register to join the conversation
Default user avatar Jerome Covington 5 years ago

Stack Overflow works well with specific questions and answers. Something as in-depth as a tutorial or book may not lend itself to "crowd-sourcing". I do think, though, that the spirit of Open Source would benefit from the effort. And I do believe it could ultimately succeed.

| Reply |
Something as in-depth as a tutorial or book may not lend itself to "crowd-sourcing"

Yea, that's the challenge - when it's short and we can all shoot out comments and vote them up/down, life is good. That's a real need - a lot of the time we just need quick answers to those questions.

With something bigger, there's a lot more coordination. But, we do it with code - which is arguably more complicated. Of course, we didn't really do it with code (a the pace we do now), until we had GitHub as a tool. What isn't clear to me - I have some ideas, but I'm good at being wrong - is what the missing tools look like for collaborative writing. But that'll be a blast to test out.

If anyone has any "it would be easier to contribute to a tutorial if..." or "I don't contribute to docs/tutorials because..." moments - share 'em!


| Reply |

Delete comment?

Share this comment

astronaut with balloons in space

"Houston: no signs of life"
Start the conversation!