Volunteer github guru for documentation submissions?

[Richard Gaskin]

Mike Kerner wrote:

> I'm done.  I have better things to do than fight through trying to
> help everybody by making the docs better.  Have a look at send and
> the attempts to clarify what it does and how it works, and if
> afterward you want a go at it, go for it.  What looks at first glance
> like a tweak turns out to be a hornet's nest that still isn't done.

Writing good docs is hard work.  We used to see a lot of "If they 
just..." comments here about the docs, but the more we participate the 
more we can appreciate firsthand that writing good documentation is no 
more trivial a task than writing good code.

I appreciate your effort in giving it a go, and there's no blame in 
taking a break from it, even if the break becomes a permanent one.

Contributions from the community are very valuable, but not an 
obligation.  The most important task any of us can do is to make great 
software with LiveCode and let others know how LiveCode helped you do 
it.  Anything beyond that is appreciated, but not required.


>  If I have realized anything in the last 24 hours it's a) Github is
> completely the wrong tool to use for documentation.  We should be
> using a wiki or something similar.  The complexity that git adds does
> not make this better.  If the goal was to open the documentation so
> that the team can spend less time working on it, and so the folks who
> use the tool all the time can improve it, then making updating the
> docs this difficult is not going to do that.  b) Trying to keep all
> the branches straight, and the complexity this adds is only going
> to make it more difficult, still.

In some ways Github is like what Winston Churchill said about democracy:

      Indeed it has been said that democracy is the worst
      form of government except for all those other forms
      that have been tried from time to time.

As I used to write here on this list, software development happened 
before Github, and it will continue to happen after Github.  Its UI/UX 
is horrifyingly opaque, designed in a fit of Dunning-Kruger Effect by 
people with IQs north of 180 who are apparently impatient with anyone 
working in a more normal range.

But over time I've come to recognize that it's the world's leading 
choice for collaborative software development.

It's no magic pony, but then again magic ponies don't exist.

We might even say it's a mess, but millions of project managers have 
found it less messy than the alternatives.

Wikis definitely simplify input, but are far less flexible with output. 
  If you're producing a web site they're often an excellent choice, but 
LC docs need to be exportable for local install, something the 
malleability of Markdown offers in spades but can be very difficult to 
do with a tool dependent on LAMP.  And wikis don't handle code at all, 
while Git provides a single set of tools for everything that comprises 
LiveCode.

One of the strengths of Git is also one of the sources of frustration 
here:  support for multiple branches.  Warts and all, Git is recognized 
by even people who dislike it as excelling at that aspect of 
collaborative workflows more than any other tool.

Branching and many other useful features of Git do indeed add 
complexity. But projects requiring branching are complex in themselves, 
and it allows that complexity to be isolated.

For relatively trivial projects branching may not unimportant, perhaps 
even distracting.  But today's LiveCode code base, needing to isolate 
the broad scope of changes in v6 and v7 on the way to v8, would not 
likely have been possible without it.


Maybe this is an opportunity to raise the bar, for both Git and 
LiveCode, to serve our own needs while showing the world how awesome 
LiveCode is:


Many years ago Ken Ray made a marvelous stack called Revzilla, a 
LiveCode plugin that served as a front-end to Bugzilla.  At the time 
many found Bugzilla's cumbersome UI off-putting, and Revzilla provided a 
way to submit and review bug requests that was much simpler and more 
convenient.

(I don't think it's been maintained through the last two rounds of LC's 
Bugzilla overhaul, but FWIW Revzilla can be downloaded here:
<http://www.sonsothunder.com/devres/livecode/downloads/RevZilla2.htm> )

I wonder if the power and flexibility of LiveCode could be applied to 
making a front-end for working with LiveCode documentation.

It would of course be ideal if the core dev team had time for that, but 
looking at the queue of things I'd like them to do and things others 
want them to do I can't say I'd want that to be a priority for them.

And ideally it needn't be.  After all, the one thing we know about the 
LiveCode community is that everyone in it knows how to program in LiveCode.

I could contribute to such a project, but I have to be realistic about 
time commitments and admit that I can't take a lead role on that.

But just maybe someone here has the intersection of time, skills, and 
interest to consider it.

If so, I'd be happy to help where I can.

-- 
  Richard Gaskin
  Fourth World Systems
  Software Design and Development for the Desktop, Mobile, and the Web
  ____________________________________________________________________
  Ambassador at FourthWorld.com                http://www.FourthWorld.com