Wiki update blockers


We aren’t making progress on the wiki update as we should. I think the main blocker of course is that we’re not a group of technical writers. However it’s really important that we have at least the basics on us and our main projects up to date on the wiki.

As I see it, we have 2 options:

  1. Re-commit to writing the pages ourselves, and scheduling more sprints
  2. Find some technical writers to interview us to write the docs

If anyone else has any other suggestions that’d be great. I think #1 is our most realistic option at this point, but we can keep an eye out for people who care about documentation to help fill out the docs once we have something in place.

Of course motivation can be a factor as well. If you’re not sure why it’s a big deal to have these docs done, let me know and I can explain better.

(Tom Farrow) #2

For me, it’s because I don’t see it as big of a deal as other things

How do I warrant prioritising this over my massive backlog of requests?
Over paid work? Over budget stuff?

(James Boston) #3

There’s a wireframe of wanted documentation here:

I could work on these pages if I know more about what the content should be. If people want to send me links to any documentation that already exists (wiki/etherpad/irc logs/whatever) I can attempt to draft something. Or you can ping me on irc (jboston). Or we could go on vidyo and you could give a brain dump in a short period.


Well a few things:

First, work can’t always be prioritized that way. You can’t be successful by only doing the urgent things. We can’t promote ourselves within the organization if it’s hard for people to understand what we do and why it’s important. A wiki page shouldn’t need as much maintenance as other tasks, and once it’s done someone else can probably handle updating it to reflect individual changes. If you are always prioritizing the issues that need more maintenance then we’ll never reap the benefits of having accurate info in the wiki.

Second, if you only have time for urgent things, then this is a different problem that needs to be solved. You shouldn’t have a massive backlog of requests, at least for Community Ops stuff. Also you shouldn’t have a massive backlog of Community Ops requests that you haven’t told the team about or asked for help with. If the massive backlog is from work or another project, the solution is still the same - let the team know you don’t have time, and give people a chance to offload the work they can do. The wiki pages are waiting on you because you have unique knowledge that we at least need you to dump, even if you don’t write pretty prose.

This is a case where a sprint makes sense. It’s hard to prioritize this task in your regular workday and so committing to a sprint gets it done, there’s a finite amount of time set aside specifically for this task and other people are there to hold you accountable.

Does any of that help?

(mrz) #5

Everything you said, of course.

I’ll only add that we should look at what we can do today that pay dividends later. In other words, what can we do that help bring in additional Participants?

Having great documentation & wiki pages feels like something that could lower the barrier to entry and work towards increasing the number of Community Ops Participants.

My favorite analogy is from racing. Consider an oval race track. Consider what happens as you approach the turn:

Better to go in slow and come out fast, than to go in fast and come out dead.
~ Sir Stirling Moss

I think we could slow our pace and work on documentation and then go faster as a team.