RapidSMS Docs Moved - Back to GitHub

[Nic Pottier]

On Thu, Jan 19, 2012 at 12:12 AM, Cory Zue <cz...@dimagi.com> wrote:
>> Sorry, the docs are down right now, I'm looking at it.
>
> Any update on this?

So ya, the server the docs were on had a bit of a meltdown. We could
have restored it, but as the wiki was the only thing running on that
RackSpace instance (and I wanted to shut down our RackSpace account as
we are wholly on EC2 now) I decided to look at what the options looked
like again.

A lot has changed since we first made the choice to move to MoinMoin.
The big argument towards MoinMoin at the time was that it could be
made to support RestructuredText, the same format used by Sphynx, and
that it has `purty` syntax highlighting.

GitHub has continued to improve its Wiki since then (and at the pace
they are going I expect it will be better yet soon) including adding
support for RestructuredText along with nice editing options if you
prefer to use Markdown:
<https://github.com/blog/774-git-powered-wikis-improved>

They also open sourced their Wiki, Gollum, which is seeing constant
improvement, while MoinMoin is completely dead as a Wiki platform.

Finally, they've added the ability to download the entire wiki via Git
and run it locally. Something that I could see being very beneficial
for people on slow connections. I've detailed that here:
<https://github.com/rapidsms/rapidsms/wiki/Editing>

Anyways, seeing that GitHub wikis have made big steps forward, that
MoinMoin is dead in the water and that I needed to rebuild a host to
get everything back up, I decided to undertake porting everything over
to GitHub instead.

All the pages that existed on http://docs.rapidsms.org/ now exist at:
https://github.com/rapidsms/rapidsms/wiki/

Most of the pages are named exactly the same, so mapping between them
should be easy. I cleaned up the front page a little bit, removing
mentions of the 'old' RapidSMS since that is long gone. I converted
all the pages to MarkDown in the process because the markup (and
specifically editor support in GitHub) is a bit cleaner. Conversion
between MarkDown and RestructuredText is pretty straightforward, so
pulling particular segments into Sphynx at some point should still be
easy.

I hope the move will help bring more contributors, not having to
create a new account should make it easier for people to contribute
and the GitHub editor is quite nice when using MarkDown.

Sorry for sort of just doing it, circumstances kind of forced my hand
and I thought it seemed like the right choice. GitHub being the
source of all documentation is probably clearer for the community as
well. If people are adamant about getting the old MoinMoin powered
wiki back then I'll spend the day rebuilding that server to get it up,
but I think GitHub is the better long term option.

Cheers,

-Nic

[David McCann]

Hey Nic--

I'll step out on a limb and say everyone's appreciative to you for both 1) hosting the docs for so long, and 2) electing to move them towards a more permanent spot with no help whatsoever.

It brings up a few questions I've been meaning to ask for a while:

1) It's always frustrating when I see a post from a newcomer, completely lost, and trying to get a RapidSMS deployment up-and-running by reading an extremely old doc that's still sitting out there.  Does anyone have any objections to a) taking an inventory of all locations of stale docs (starting point: http://groups.google.com/group/rapidsms/browse_thread/thread/1bc8adae56477c1e) and b) killing them (and any google group threads mentioning them) and/or pointing anyone coming to those pages towards a single, authoritative place for up-to-date (well, the best we have anyway) documentation?  Also, now that Wikipedia is no longer "going black," I might consider taking a stab at the somewhat-sad-and-stale wikipedia entry: http://en.wikipedia.org/wiki/RapidSMS which doesn't mention Rwanda, Uganda, or Caktus as pertinent projects/stakeholders (kind of a wtf in my opinion).

2) I'd propose that that authoritative place EITHER be a) github's wiki, or b) readthedocs.org.  I'd prefer readthedocs, as we can keep the docs under source control on github and automatically deploy them with version tagging.  Although maybe I'm not up-to-date on github, or other best practices for hosting documentation?

In any case, I've got some spare cycles to move things around, and just wanted to sort of get a feel for what people's opinions were.  If anyone's got strong opinions let me know, and I'll start working on moving things forward.

--dm

--
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.

[Colin Copeland]

On Thu, Jan 19, 2012 at 6:52 AM, David McCann <david.a...@gmail.com> wrote:

2) I'd propose that that authoritative place EITHER be a) github's wiki, or b) readthedocs.org.  I'd prefer readthedocs, as we can keep the docs under source control on github and automatically deploy them with version tagging.  Although maybe I'm not up-to-date on github, or other best practices for hosting documentation?

I second readthedocs.org (or some form of sphinx docs). I started a docs/ directory in the feature/new-routing branch to outline the updates and changes associated with the branch and it worked great:

https://github.com/rapidsms/rapidsms/blob/feature/new-routing/docs/releases/0.9.7.rst

Sphinx will give us a little more flexibility and, as David mentioned, can easily be setup with version tagging, which is a nice plus. Anyways, +1 for me!

Colin

--
Colin Copeland, Managing Member
Caktus Consulting Group, LLC
http://www.caktusgroup.com

[Cory Zue]

Hey Nic,

Just wanted to say thanks for taking care of this and so quickly. I'm
very happy to have the docs located much closer to the source. I don't
know enough about the tradeoffs between the github wiki and
readthedocs to comment on that, but trust you guys to do whatever
makes sense.

cheers,
Cory

[Tobias McNulty]

On Thu, Jan 19, 2012 at 8:30 AM, Colin Copeland <cop...@caktusgroup.com> wrote:

On Thu, Jan 19, 2012 at 6:52 AM, David McCann <david.a...@gmail.com> wrote:

2) I'd propose that that authoritative place EITHER be a) github's wiki, or b) readthedocs.org.  I'd prefer readthedocs, as we can keep the docs under source control on github and automatically deploy them with version tagging.  Although maybe I'm not up-to-date on github, or other best practices for hosting documentation?

I second readthedocs.org (or some form of sphinx docs). I started a docs/ directory in the feature/new-routing branch to outline the updates and changes associated with the branch and it worked great:

https://github.com/rapidsms/rapidsms/blob/feature/new-routing/docs/releases/0.9.7.rst

Sphinx will give us a little more flexibility and, as David mentioned, can easily be setup with version tagging, which is a nice plus. Anyways, +1 for me!

This probably goes without saying, but +1 from me as well. :-)

Just so folks have something to look at, this is how the above file would look on readthedocs:

http://rapidsms.readthedocs.org/en/latest/releases/0.9.7.html

For folks who haven't used it before, one of the things I particularly like about readthedocs is that it automatically builds the docs *every* time you commit, so you always have a pretty, up-to-date copy of the latest development documentation.   It's kind of like a Continuous Integration server for your documentation.

Nic, despite my enthusiasm for readthedocs, I'm particularly grateful for everything you've done to manage the docs up until this point - especially, as Cory said, responding so quickly to the outage and giving us something we can use immediately!

Cheers,

Tobias

--
Tobias McNulty, Managing Member

[Nic Pottier]

>> I second readthedocs.org (or some form of sphinx docs). I started a docs/
>> directory in the feature/new-routing branch to outline the updates and
>> changes associated with the branch and it worked great:

I do really like ReadTheDocs as well, it is a pretty fantastic way of
distributing documentation. With online editing of files in GitHub it
even makes submitting documentation updates pretty painless.

If people want to see what is possible with ReadTheDocs, here's our
docs for XForms and Smartmin:

http://rapidsms-xforms.readthedocs.org/en/latest/index.html
http://smartmin.readthedocs.org/en/latest/quickstart.html

In short, ya, they rock. :)

-Nic

[David McCann]

Hey Folks--

For your review, I've ported over the documentation to the rapidsms repo itself (built to rapidsms.readthedocs.org), previously on https://github.com/rapidsms/rapidsms/wiki previously on docs.rapidsms.org.

I'd really love to kill any stale documentation that's out there, seems like it's a common complaint of newcomers (even the documentation itself still points to random stuff like http://roballen101.posterous.com/installing-rapidsms-from-scratch-oct-2010).  If everyone's +1 on what's at rapidsms.readthedocs.org, I'd like to pull down the content on the wiki, and also close out any previous threads on the group pointing to this latest version of the doc.

In the longer-term, it might be cool to have some sort of automated process that syncs between the github wiki and the docs actually in rapidsms/docs, as there is an added benefit to keeping the documentation on the wiki (much easier for anyone to add documentation), but for the time being I'd really love to see a single authoritative location for the docs.

Thoughts?

--dm

[Derek Dohler]

Not sure whose +1s count, but when I was first learning RapidSMS, I fought with the outdated docs, so I give my hearty +1 to killing stale docs.

Derek

[Cory Zue]

+1!

Thanks David!

Cory

2012/2/8 Derek Dohler <doh...@gmail.com>

[Trevor Sinkala]

+1

Thank you,
Trevor

[Victor Miclovich]

+1

[stephen osewe]

Hallo guyz,

I really like ReadtheDocs,its pritty amazing and the docs layout looks
nice and inviting...I was following up on the installation aspect and
N0.# seems not to be clear

i.e
5 - Create a new project¶

$ rapidsms-admin.py startproject myproject
$ cd myproject

The confussion for newbies will come at not knowing at which folder or
location do they run these commands,can that be clarified?

On Wed, Feb 8, 2012 at 3:26 PM, Victor Miclovich <vicmic...@gmail.com> wrote:
> +1

>
> --
> 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.
>

--
stephen osewe
websys software solutions
www.websysltd.com
+254-721-765 824
in...@websysltd.com

[Victor Miclovich]

Hello Stephen,

On Wed, Feb 8, 2012 at 4:47 PM, stephen osewe <stephe...@gmail.com> wrote:

Hallo guyz,

I really like ReadtheDocs,its pritty amazing and the docs layout looks
nice and inviting...I was following up on the installation aspect and

The docs definitely looks nice 

N0.# seems not to be clear

i.e
5 - Create a new project¶

$ rapidsms-admin.py startproject myproject
$ cd myproject

The confussion for newbies will come at not knowing at which folder or

rapidsms-admin.py is analogous to django-admin.py and should be run anywhere readable in your system (file system) where you probably keep source code of other projects that you develop.

Other commands run, are usually run as cron jobs or using inside the folder that is created after running rapidsms-admin.py startproject myproject where <myproject> is the folder. such commands can be django default management commands such as 

• syncdb (python manage.py syncdb)
• createsuperuser (python manage.py syncdb)
• etc.

Ideally there are local and global "management" commands. I think that should clarify this for you.

location do they run these commands,can that be clarified?

I think that clarification will be put in place. 

[Tobias McNulty]

On Wed, Feb 8, 2012 at 8:58 AM, Victor Miclovich <vicmic...@gmail.com> wrote:

On Wed, Feb 8, 2012 at 4:47 PM, stephen osewe <stephe...@gmail.com> wrote:

location do they run these commands,can that be clarified?

I think that clarification will be put in place. 

Good call.  I made a small change to #3 and #5 that hopefully helps clarify the directory locations somewhat:

http://rapidsms.readthedocs.org/en/latest/installation/debianbased.html