[OH-Dev] Entry barrier for OpenHatch info improvements

[Asheesh Laroia]

Hi anatoly!

On Sun, 23 Dec 2012, anatoly techtonik wrote:

> Hi,
>
> I was looking into administration stuff on OpenHatch Wiki (it's very
> awesome to have this knowledge online), and I've noticed that it moved to a
> rigid reST documentation system.
>
> IMHO by this move you significantly raise the entry barrier for new people
> and move more and more away from the problems newbies are experiencing when
> they start.
>
> https://openhatch.org/wiki/Chat_with_us_on_IRC_(moved)
>
> Because! if wiki is easy to edit, they can solve the problem and share. 
> The cost of sharing on the wiki is registration and login (already high, 
> because it doesn't work ATM with my Google email and keyboardless login, 
> BTW).

Yes, hmm.

(On a side note: It *should* work with your Google email, although I guess 
it doesn't work keyboardlessly since you have to click the Google logo, 
unless you tab to it and press enter. Maybe we can make that work 
better.)

> The GitHub way of editing things may raise an itching feeling for you,
> because the whole toolchain is exciting and because you probably edit it in
> your favorite editor. Otherwise I can't understand why move there, because:
>
>  1. reST pages require installed things to preview your edits
>  2. you need to invoke three actions to share in case you have the
> checkout - find, edit, compile, browser refresh, which are itself complex
> actions, involving many keypresses and mouse clicks, instead of simple -
> login, edit, save - ony three full simple actions
>  3. forcing people to setup the whole toolchain just to share docs is a
> torment, and not an education

Aww re: torment

I kind of agree. I'll say there are a few things we get from it, in order 
of what I like the most:

* A sense of linearity of the documentation. I felt like the one big thing 
we were missing a year ago with our on-wiki documentation was that it was 
hard to get a sense of what documentation existed, and I think people 
(certainly myself) were getting lost without that clarity. So I really dig 
the way the table of contents at 
http://openhatch.readthedocs.org/en/latest/ works.

* Since http://openhatch.readthedocs.org/en/latest/ is hosted off-site, in 
case the site does go down, it's not super difficult to read the 
documentation on the server. (We could get the core of that benefit by 
just having sysadmin-oriented docs in an offsite system.) * More options 
for formatting, and smarter layout of Python code. You can see this in the 
training missions documentation here: 
http://openhatch.readthedocs.org/en/latest/tutorials/writing_missions.html

* The hypothetical (we haven't used it much/at all yet) ability to have 
some code-oriented documentation live directly inline with the code, 
through the extraction of information from docstrings.

* When you do a 'git clone', you now can be fairly assured that the code's 
documentation has not gotten out of date from your copy of the code.

It does create a barrier, though; I agree.

The way I've been thinking about it is that the wiki is not deprecated 
entirely by any means; instead, code-oriented docs should go in 
oh-mainline's doc/ directory (or is it docs?), and project-oriented and 
other content should go on the wiki.

We can address a small part of the barrier by asking people to use Github 
and pull requests to make edits. We'd have to add "edit" links to e.g. 
http://openhatch.readthedocs.org/en/latest/tutorials/writing_missions.html 
but that's not totally out of the question. I'm not thrilled about the 
idea of relying on more Github-specific functionality, but maybe that'd be 
OK.

Let me know what you (and the rest of OH-Dev) think.

-- Asheesh.