RapidSMS Wiki

[Nic Pottier]

Ok so based on the comments on the documentation it seemed like
everyone thought a (better) wiki would be a Good Thing. (tm)

I spent a bit of time today hacking on MoinMoin, which I really can't
say anything good about, but I did eventually convince it to do what I
wanted.

It basically acts almost exactly like Sphinx now and includes pretty
Pygment-enabled code highlighting. The big win there is that any
pages that the community builds up can easily be rolled into the
'real' Sphinx documents with minimal fuss.

Give it a spin, let me know what you think, right now it is just a
playground to test features out, there's still some configuration I
have to do, namely email. If the community approves then I'll throw
together more of a skeleton for the page contents. Or better yet,
you can start on that, it is a wiki after all.

<http://rapidsms.nyaruka.com/>

(DNS entry is new, wait a bit if it doesn't resolve)

-Nic

[Matt Berg]

Nic,

Sorry for not replying earlier.  This looks pretty awesome.

Quick question.  Does MoinMoin store things as flat files? If so, maybe we can manage edits via git if people want to work that way too.

Nic, would you mind hosting the doc site initially?  If it's cool, let's just point docs.rapidsms.org to your site for now and get started.

We need to get the install/setup instructions back up.  Tim wrote a nice tutorial earlier that we could update and use.

Thanks,

Matt

--
You received this message because you are subscribed to the Google Groups "rapidsms" group.
To post to this group, send email to rapi...@googlegroups.com.
To unsubscribe from this group, send email to rapidsms+u...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/rapidsms?hl=en.

--
ICT Director
Millennium Villages Project
Columbia University, NYC
M: +1.646.463.1273
Skype: mlberg

[Cory Zue]

Thanks for putting this together Nic. I think it looks great.

I'm also curious about how you see this being edited/maintained.
Would we still have a documentation repo or would the edit history of
the wiki be the source of truth?

On Mon, Jul 5, 2010 at 5:59 PM, Matt Berg <mlb...@gmail.com> wrote:

> We need to get the install/setup instructions back up.  Tim wrote a nice
> tutorial earlier that we could update and use.

Matt, I'm on the hook for producing this. Am hoping to have a draft
written by next week's Wednesday skype.

Cory

[Tobias McNulty]

I agree it looks good and thanks for taking the time to set it up, Nic!

I'd still prefer the dual approach, with the intent being the "official" docs end up in the documentation repo at some point.

That said, I think it's still important to emphasize that having a wiki does not mean the devs are freed of writing docs.  :-)

Best

Tobias

Tobias McNulty
Caktus Consulting Group, LLC
P.O. Box 1454
Carrboro, NC 27510
USA: +1 (919) 951-0052
http://www.caktusgroup.com

[Nic Pottier]

Hi guys,

Sorry for the late reply, been off the grid for a few days.

A wiki is obviously just a tool, how we use it is obviously up to us.
I put this together because on the call (and list) there seemed to be
a push to have something that would be easier to edit while still
looking reasonably pretty..

I think if we are realistic, it is unlikely that the core devs are
suddenly going to start writing documentation as they write new code.
So a wiki makes it a bit easier for other people to record their
learnings as they hack their way through it. For example I was
fighting a bit with some GSM modems this weekend and the Wiki seems
like it would be a great place to record debugging instructions for
that type of thing etc..

Really good documentation requires at least a few dedicated owners who
organize the structure, there's no real way around that, wiki or not.
But the wiki does allow more people to participate, and personally I
think it is a tad easier environment than the Sphinx route.

I suppose there still remains the question, who and how are we going
to build out the Sphinx docs, and should we continue to go down that
(currently not working) approach? It would probably be better to have
one repository for documentation rather than both a Wiki and Sphinx.

For the sake of driving towards a resolution, I'm just going to be all
crazy and propose we put all documentation on the Wiki. People should
still comment their code in PyDoc format, but at least for me, those
API docs are almost always read in my code editor, not a web browser,
since the source is the ultimate documentation at that level.

Higher level documentation, ie, how components work, architecture,
howtos, troubleshooting, system design and advice, should all live in
the Wiki. That allows more people to contribute and the editing is
easier. It also addresses the whole problem of who gets commit rights
and where.

-Nic

[Tobias McNulty]

Thanks, Nic. I'm supposed to be on vacation, but I couldn't resist responding. :-)

I guess all odds are pointing against my hopes of keeping at least some docs in version control. Briefly, two things:

1) We can do better than the status quo. Wiki or not, it is absolutely imperative that devs write docs for new code. The attitude that "it won't happen" is entirely counterproductive. It's a matter of educating developers about the value of things like good documentation and unit tests. These are part of any good open source project, and if you want anyone to use your code, you have to provide them. Period.

2) I agree that having a few dedicated owners is paramount to good documentation, especially when a wiki is involved. Who volunteers to be on, or how do we select, a team of "core documenters" and what are the responsibilities of this team?

Yours,
Tobias

Sent from my mobile device.

> Thanks for putting this togethe...

--

You received this message because you are subscribed to the Google Groups "rapidsms" group.

To post ...

[Nic Pottier]

> 1) We can do better than the status quo. Wiki or not, it is absolutely
> imperative that devs write docs for new code. The attitude that "it won't
> happen" is entirely counterproductive. It's a matter of educating developers
> about the value of things like good documentation and unit tests. These are
> part of any good open source project, and if you want anyone to use your
> code, you have to provide them. Period.

Yes of course, I couldn't agree more.

But how?

What do you do if people refuse to write unit tests or docs? Kick them out?

-Nic

[Tobias McNulty]

Keep asking. :-)

Sent from my mobile device.

On Jul 8, 2010 2:26 PM, "Nic Pottier" <nicpo...@gmail.com> wrote:

> 1) We can do better than the status quo. Wiki or not, it is absolutely

> imperative that devs writ...

Yes of course, I couldn't agree more.

But how?

What do you do if people refuse to write unit tests or docs?  Kick them out?

-Nic

--

You received this message because you are subscribed to the Google Groups "rapidsms" group.

To post to this group, send email to rapi...@googlegroups.com.
To unsubscribe from this group, send...

[Cory Zue]

On Thu, Jul 8, 2010 at 2:32 PM, Tobias McNulty <tob...@caktusgroup.com> wrote:
> Keep asking. :-)

I definitely agree with you too, Tobias. But our overly aggressive
commit rules were one of the reasons there has been so little
development in the rapidsms core in over a year. Granted, this had
much more to do with process than with test coverage and docs, but I
still think we may not be at a mature enough point in the code base to
have rules that are this strict. It reminds me a bit of the
Nupedia/Wikipedia distinction. At first Nupedia was a protected
garden of peer-reviewed, expert-written knowledge, and after 3 years
they had exactly 24 articles. Then they opened it up to everyone and
wikipedia was born. (Not that I'm claiming we'll have that kind of
success, but I do think there's something to be said for giving people
the tools and freedom to produce what they want and hoping they
self-motivate and self-police).

I'm +1 on Nic's proposal to move everything to a wiki.

I'm also +1 on Tobias's proposal to elect a team of "core documenters"
and I'll volunteer to be on the team and help figure out what's
necessary and how we can organize ourselves and our docs.

Cory

[kieran sharpey - schafer]

Hey,

I also agree with Nic's wiki proposal, allowing implementers to also update user documentation (they're often keener at it than the original devs!).

I do have a question(s):
* how is this different to using the wiki on github? its just sexier?
* how is this different to using the wikibook where everything is at the moment? is it just sexier?

I'm just trying to think through how coders and implementers will get to / and interact with the wiki - and how it will better than our previous efforts.

Cheers,
Kieran

--
Kieran Sharpey-Schafer
unicefinnovation.org

[Tobias McNulty]

Hey all,

For the sake of trying something new (apparently we've been doing hasn't worked so far) and finally having a decision, let's put all documentation efforts towards the wiki!

Rest assured, I haven't been convinced of the technical superiority of wikis, but I think it's certainly worth a try.  Given that the wiki uses reST, we can always start pulling the more polished docs into sphinx/git if it seems appropriate or the wiki starts to get out of hand.

Nic's told me that he's fine with hosting the site and would just need a CNAME setup to point to his server.  Can we move docs.rapidsms.org to docs-old.rapidsms.org (or something) and make docs.rapidsms.org point to the new wiki?

All that sound okay?  Revisit in 6 months or so and see where we stand?

Cheers!

Tobias

P.S. I can't help but notice that, to date, developers are the only ones who've volunteered to be on this new team of wiki-documenters.  Come forward, ye non-dev documenters who will save us all! :-)

[kieran sharpey - schafer]

Hey RapidSMS,

Just an update- we got the http://docs.rapidsms.org wiki up and running, thanks to Nic. So moving forward:

1. The next phase is to populate it as we go, we currently have 5 different sources of documentation that we need to consolidate:

Current Documentation Sources:

• http://www.rapidsms.org/code/reference/documentation/ 

• http://wiki.github.com/rapidsms/rapidsms/

• http://drop.io/howtorapidsms

• http://github.com/rapidsms/rapidsms-documentation

• http://en.wikibooks.org/wiki/RapidSMS_Developers_Guide (an extensive amount of practical topics added by the guys from souktel.org)

please post to list if there's any others out there.

2. also we've started planning an outline for the docs here: http://etherpad.unicefinnovation.org/196 please do add anything thats missing or links to existing docs we need to included.

3. Date! The doodle is still up for the 'design & documentation day' at http://doodle.com/ers76bkrk967bdss but its not looking like thats going to work. Perhaps we can figure it out on the next RapidSMS call (well not call, irc meeting) this coming Wednesday.

Best,
Kieran

----------------------------------------------
Kieran Sharpey-Schafer

mobile: +27 72 371 6469 (SA)
mobile: +1 347 703 9280 (US)
twitter:   @ksharpey
skypeid: kieran.sharpey.schafer