[OH-Dev] Entry barrier for OpenHatch info improvements

[anatoly techtonik]

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


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

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


> 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<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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openhatch.org/pipermail/devel/attachments/20121226/ab783cd9/attachment.html>