Making the docs more open to community contributions

[HansBKK]

I am of the opinion that accurate, continuously updated and improved documentation is of critical importance to the long-term success of any non-trivial software package, and as a New Yorker, adhere to the "broken windows" theory. I also feel that FOSS developers shouldn't have to spend much time on the documentation side of their projects, ideally limited to developer-targeted areas where "mere mortal" community members simply don't have the required knowledge. In particular, user-level howto's, especially those targeting the newbie, are IMO best written by those still relatively new to the program - obviously with more experienced members "looking over their shoulder" to correct any inaccuracies, linking to more in-depth pages where appropriate etc. Simple typo's, grammar fixes and stylistic improvements should be quickly and easily done by an community member right then and there as they are reading and notice the suboptimal content.

Personally, I've been trying to make myself useful in those few areas such as these where I can, but have to admit feeling a bit frustrated when even obvious and tiny corrections need to be logged to the bug tracker, where of course they must sit in deference to higher priority demands on the developers' time ("bump examples" cited at the bottom of this post).

For example, the time that might be spent creating and maintaining an all-in-one Windows package would IMO be much better invested in a centralized documentation store accessible to editing by the community beyond the usual suspects.

May I be so bold as to suggest a specific wiki platform: DokuWiki could serve up Leo-derived @shadow files directly - it doesn't use a database, the wiki data store is plaintext files. It has fine-grained ACLs if that's an issue, and you could use its version control or any VCS you like to check out the "public edits/contributions" before incorporating them into the "canonical" documentation shipped in the .leo files. Filesystem directories can serve as namespaces, e.g. separating HowTos from Reference, or user-level from developer, however you like.

IMO so many areas of the current wiki are now so out of date the project would be better served by simply wiping it.


====================

Past docfix suggestions - note I don't presume my suggestions be adopted wholesale, simply for the issues raised to be considered and either implemented or rejected, rather than remaining in limbo.

http://webpages.charter.net/edreamleo/installing.html#required-and-optional-packages

still reads "Leo also requires either the Qt widget set."

and the broken link is still cited here:

http://webpages.charter.net/edreamleo/FAQ.html#how-can-i-display-graphics-in-leo

Along with the some other doc fixes I've logged here:

https://bugs.launchpad.net/leo-editor/+bug/905276

Also, search LeoDocs for "tk" and you'll find lots of now-irrelevant bits to archive out.

[Terry Brown]

On Thu, 5 Jan 2012 08:50:58 -0800 (PST)
HansBKK <han...@gmail.com> wrote:

> Personally, I've been trying to make myself useful in those few areas such
> as these where I can, but have to admit feeling a bit frustrated when even
> obvious and tiny corrections need to be logged to the bug tracker

The barrier to contributing to the docs. is knowing how to use bzr to
push to the trunk, which means setting up a ssh key for your launchpad
account. If you can do that you can edit the docs. in
Leo .../leo/doc/LeoDocs.leo and commit and push the changes yourself.
Once your launchpad account is a member of the leo-editor-team, of
course, but that's easy.

Cheers -Terry

[zpcspm]

On Jan 5, 8:25 pm, Terry Brown <terry_n_br...@yahoo.com> wrote:
> The barrier to contributing to the docs. is knowing how to use bzr to
> push to the trunk

And also having a minimum amount of knowledge about rst

[Matt Wilkie]

I think Hans' observation that the best docs are written by newcomers
who learning their way about, with over the shoulder corrections and
refinements by those more experienced, is spot on.

> The barrier to contributing to the docs. is knowing how to use bzr to
> push to the trunk, which means setting up a ssh key for your launchpad
> account.  If you can do that you can edit the docs. in
> Leo .../leo/doc/LeoDocs.leo and commit and push the changes yourself.

For me, installing bazaar, learning some basics, and setting up an
launchpad ssh key was easyish, but not easy. I think if I hadn't
already had a year or so of using tortoise-svn and prior experience
with ssh under my belt it would have been difficult. So yes, I'd still
call this a barrier.

I agree that the existing wiki might be better turned off, saving a
number of pages which are still germane for placement elsewhere. I'm
not sure that using a newer shinier wiki platform in it's stead would
get at what I see as the deeper cause: the user contributed docs being
in a separate world from where the developers live.

It doesn't operate this way now, but at one time effbot.org would
accept edits from anybody, but not publish the edits until they'd been
accepted. On submission of an edit the web host would generate a
unified diff file and fire it off it to the maintainer (Fredrick
Lundh). If Fredrick liked the edit he'd patch and save, and that would
be the new web page. I always thought this a very elegant solution and
wished it showed up in the tools I've used for my websites.

How difficult would it be to have DokuWiki (or MoinMoin or ...) push
edits to a leo-editor-website bzr banch that has standing merge to
trunk request? And how much work would it be for members of leo-editor
team (or leo-website team) to accept/reject these pushes?

--
-matt

[Terry Brown]

On Sun, 8 Jan 2012 21:26:42 -0800
Matt Wilkie <map...@gmail.com> wrote:

> How difficult would it be to have DokuWiki (or MoinMoin or ...) push
> edits to a leo-editor-website bzr banch that has standing merge to
> trunk request? And how much work would it be for members of leo-editor
> team (or leo-website team) to accept/reject these pushes?

Another not necessarily better but different option would be to keep
all the docs. in Leo/rst and use the bzr Python bindings to have Leo
push changes to some place for merging. I.e. automate the bzr part
of the process. Not exactly sure how complicated that would be to set
up / use, but it would keep the docs. in the Leo rst system, which seems
desirable to me.

Cheers -Terry

[Edward K. Ream]

On Mon, Jan 9, 2012 at 9:03 AM, Terry Brown <terry_...@yahoo.com> wrote:

> Another not necessarily better but different option would be to keep
> all the docs. in Leo/rst and use the bzr Python bindings to have Leo
> push changes to some place for merging.  I.e. automate the bzr part
> of the process.  Not exactly sure how complicated that would be to set
> up / use, but it would keep the docs. in the Leo rst system, which seems
> desirable to me.

I've played around with bzr hooks from time to time. It's easy enough to do.

The problem, as I see it, is that everybody would have to install the
hooks. Hmm, a new thought: the easy way would be to create a Leo bzr
plugin. Of course, even that is an extra step, and a significant
one.

Edward

[HansBKK]

On Monday, January 9, 2012 12:26:42 PM UTC+7, Matt Wilkie wrote:

I'm not sure that using a newer shinier wiki platform in it's stead would get at what I see as the deeper cause: the user contributed docs being in a separate world from where the developers live.

Perhaps I wasn't clear enough; what I was proposing would eliminate this separation.

1. The developer's Leo files push plaintext out via @ <files>, most likely shadow? They could even have rst markup if/where that's important.

2. They get served up, directly and as-is, by DokuWiki - plaintext files **are** its native datastore. In effect the @files are available on the web for you, me and Joe Blow to edit - subject of course to whatever open/secure balance the developers desire.

3. Periodically the updated text is compared with the "canonical" original, most likely via the developers' preferred diffing tools, however DokuWiki also has its own history/scs built-in (to use or ignore).

4. The developers merge those edits they approve back into their canonical .leo files, then push these back out to the wiki's filesystem - easy to reset the DW-internal history at that point as well, start off with a blank set each round.

5. Rinse cycle repeat. I think the most frequent cycle if there were a lot of doc improvements by the community would be monthly, otherwise quarterly would probably suffice. I'd be willing to act as sysadmin/liason/coordinator in keeping things on the wiki in order, but of course won't be able to technically vet content changes beyond my pay grade. . .

I'd also, alternatively, be willing to climb the bizarre learning curve if I had a little handholding to make sure I wasn't messing up anything important, but I honestly think making it quick and easy for any Leo user spotting a docs error to quickly fix it themselves, would be a good thing.

Not to mention having everything in one place for searching - right now there's a learning curve to getting familiar with how the docs are structured, which IMO shouldn't be there, especially for the stuff important for newcomers.

[Terry Brown]

On Mon, 9 Jan 2012 08:07:26 -0800 (PST)
HansBKK <han...@gmail.com> wrote:

> 2. They get served up, directly and as-is, by DokuWiki - plaintext files
> **are** its native datastore. In effect the @files are available on the web
> for you, me and Joe Blow to edit - subject of course to whatever
> open/secure balance the developers desire.

My thought was that if Leo is a premier platform for editing rst, as we
like to believe it is, it should work as an environment for editing
documentation for Leo, by anyone. One requirement would be to avoid
forcing the user to set up bzr / ssh / launchpad. That part could
probably be handled by Leo itself.

I like DokuWiki well enough, used it once long ago, but I think we need
to think hard before tying ourselves to having things running on
platform XYZ. If we revamp Leo's hosting say by moving from LP to
bitbucket, there'd be a strong argument for accepting bitbucket's wiki
system, whatever it is.

Right now I don't think we have developer time for any major changes,
unless we add more developers... :-)

I understand you're trying to avoid using developer time here,
and I suppose in theory the DokuWiki stuff could be completely separate
from the Leo distribution process and require no developer input beyond
responding to requests to check new content. But Leo already has way
too many homes on the web, so we need plan carefully before adding more.

Cheers -Terry

[Matt Wilkie]

Thanks for the clarification Hans.

Terry said:
> My thought was that if Leo is a premier platform for editing rst, as we
> like to believe it is, it should work as an environment for editing
> documentation for Leo, by anyone.

One point putting some weight towards wikidom is that things like
typo's etc are best fixed in situ, where the itch and the urge to
correct are matched in time and space. Myself, I tend to use web pages
for reading docs. I like the rich text, easy up/down of font size with
ctrl-+/-, multiple tabs, and so on. I find reading and navigating
Leo's docs inside Leo more cumbersome (maybe I just haven't tried hard
enough).

Idea: I'm reading
http://webpages.charter.net/edreamleo/installing.html#installing-leo-on-windows,
see something to fix or add to, and click the [edit] link in the
sidebar. The browser calls Leo, which opens that file and outline
location. I make my changes, save, and push "email to launchpad"
button.

The edit link url might look like:

leo://$leo-root$/LeoDocs.leo/Users_Guide/Installing_Leo/@file_installing.txt/Installing_Leo_itself/Installing_Leo_on_Windows

--
-matt

[Terry Brown]

On Mon, 9 Jan 2012 23:13:42 -0800
Matt Wilkie <map...@gmail.com> wrote:

> I find reading and navigating
> Leo's docs inside Leo more cumbersome (maybe I just haven't tried hard
> enough).

I agree they're nicer to read in a browser.

> Idea: I'm reading
> http://webpages.charter.net/edreamleo/installing.html#installing-leo-on-windows,
> see something to fix or add to, and click the [edit] link in the
> sidebar. The browser calls Leo, which opens that file and outline
> location. I make my changes, save, and push "email to launchpad"
> button.
>
> The edit link url might look like:
>
> leo://$leo-root$/LeoDocs.leo/Users_Guide/Installing_Leo/@file_installing.txt/Installing_Leo_itself/Installing_Leo_on_Windows

Very clever idea. I think the URL would need to be something like
http://webpages.charter.net/edreamleo/link/lnk2156.lnk. The content of
the file would be something like you give above. The user would
have to set up Leo or a script which calls (or launches) Leo as the
handler, so installation would need to be polished, but it's still a
neat idea.

Cheers -Terry

[mdb]

Some inline comments

>>I find reading and navigating
>>> Leo's docs inside Leo more cumbersome (maybe I just haven't tried hard
> enough).

> I agree they're nicer to read in a browser.

HTML browsing is already builtin in some sense through the viewer and
@url, but could be easier turn on and control.

>> One requirement would be to avoid
>> forcing the user to set up bzr / ssh / launchpad. That part could
>> probably be handled by Leo itself.

> > see something to fix or add to, and click the [edit] link in the
> > sidebar. The browser calls Leo, which opens that file and outline
> > location. I make my changes, save, and push "email to launchpad"
> > button.

I agree on these points. I think it would be a big step forward in
encouraging both code development and documentation improvement to
have a Leo Developer version that has these as built in functionality

--create Launchpad lp:leo-editor account with push capability for new
users (I recall setting up keys for ssh is complicated)
--authenticate lp account
--both bzr push and bzr pull (with auto reload)

One potential hangup would be integrating lp authentication and bzr
access in Leo and retaining platform independence. Not sure of
relying on the python bzr library is necessary, vs the more reliable
command line method.

[HansBKK]

I've always disliked the expression "eating your own dog food", but it's a good principle when the use case fits the project, and I think Leo's a flexible enough tool that the primary principle behind my OP can be accomplished without too much trouble.

My central point is time and energy invested in the project documentation process should be in the direction of lowering the technical barriers for those not already bazaar-familiar developers to get involved. If one's already gone to the trouble of becoming part of the Leo documentation team, setting up the toolchain etc then surely they're familiar enough with where things are located that navigating to the node that needs fixing becomes a trivial matter.

The barriers for this latter group is probably more a lack of motivation than technical issues, and rightly so, they've got more important and interesting things to work on. It's the group of people relatively new to Leo, in the first flush of enthusiasm getting to know the project at the lower level on-ramps of the learning curve - this is the group that IMO should be tapped - let's look at how to make use of Leo's openness and customizability to empower them.