[OH-Dev] Entry barrier for OpenHatch info improvements

[Asheesh Laroia]

First of all... please accept my apologies for not letting this through 
moderation until right now. I've added you to the whitelist; I meant to do 
that earlier.

On Wed, 26 Dec 2012, anatoly techtonik wrote:

> On Wed, Dec 26, 2012 at 7:58 PM, Asheesh Laroia <asheesh at asheesh.org> wrote:
>       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.)
> 
> 
> mouseless != keyboardless =)
> 
> Hmm. I've just opened the page and it appeared that I've logged in. I guess it is a page caching
> issue. Cache is not invalidated after I've logged in, so I've got the the same page as before and
> was confused.

*nod*

Good to know that is the reason, at least.

>       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.
> 
> 
> In my opinion there are only two rules. Things that are irrelevant to code, that might break and
> don't require an ordered multipage explanation, reference gathered by crowdsourcing, is better
> maintained in the wiki. From the other side even code related documentation sometimes looks good
> on the wiki. It depends on organization. One of the best organization of documentation materials
> for open source project I've seen is:
>  
> http://ufoai.org/wiki/Contribute
> 
> Trying to make the http://ufoai.org/wiki/TODO/Roadmap with Sphinx and teach people how to work
> collaboratively on this is not as simple and intuitive as this thing. When I think about the way
> an open source should look to be attractive and challenging for me as a developer, I imagine a
> page like this - http://ufoai.org/wiki/TODO/Mapping/Crafts_Tiles

Wow! Those are some truly great pages!

I'm coming around to your way, but I'd like to hear Daniel's thoughts, who 
helped us begin the Sphinx transition. I would hate to put ourselves in 
the position of needing to spend time moving documents back to the wiki 
where we used to have enough enthusiasm for keeping them in Sphinx, and 
then the resulting wiki docs will be a haphazard mess and we'd have wished 
we never moved back.

So anyway, to be clear: The place for code docs is still "docs/" in the 
repository, which gets rendered by Sphinx and pushed to 
openhatch.readthedocs.org.

> Seems like a good direction for the OpenHatch project would be providing 
> a service for projects to draw and close such roadmaps, learn by 
> completing activities (and not by reading texts). In this regard I see 
> OH more like specialized Khan Academy. I am even interested to 
> contribute to the cause, but AGPL is somewhat between an excuse and 
> limitation. =)  

I am actually fairly happy to think about relicensing the code!

I intend to get oh-bugimporters/ relicensed under Apache License 2.0 if 
the contributors are willing.

(And your contributed code can be under Apache License 2.0 if you want to 
get a headstart.)

I think you're right that we're all about learning by doing -- I'm glad 
that shines through the site!

>       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.
> 
> 
> Except that I have to remember password every time I go to GitHub from 
> new box, the edit button on Sphinx page is one awesome idea. I tried to 
> do a web-framework-independent editor for Spinx pages, but lost in 
> AppEngine implementation details long ago.

*nod*

-- Asheesh.