Volunteer github guru for documentation submissions?

[Mike Kerner]

The process for modifying code and the process for modifying documentation
should be different.  Git, maybe intentionally, makes it difficult for
people to work together on documents.  One of the things that Ali and I ran
into is that he cannot easily make changes to my changes because that's not
the way git is designed.  So, if I have something I screwed up (like some
of the tags), his only option is to write a missive about it.  A few
hundred words later, and he has spend a lot of time writing, but I don't
understand so a few hundred words more, and I think I understand what he is
saying, so I make a change but something else is messed up and so we go
back and forth and all we have manged to do is write a lot of words but not
fix anything.

And I'm in the wrong branch.  I won't be the only person to do that,
either.

If git is going to be the tool, then there needs to be a pre-tool.  If that
pre-tool is a mailing list, then so be it.  I'll send my last version of
send, and y'all can have at it, if you choose.

On Wed, Apr 13, 2016 at 10:42 AM, Richard Gaskin <ambassador at fourthworld.com
> wrote:

> 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
>
>
>
> _______________________________________________
> use-livecode mailing list
> use-livecode at lists.runrev.com
> Please visit this url to subscribe, unsubscribe and manage your
> subscription preferences:
> http://lists.runrev.com/mailman/listinfo/use-livecode
>



-- 
On the first day, God created the heavens and the Earth
On the second day, God created the oceans.
On the third day, God put the animals on hold for a few hours,
   and did a little diving.
And God said, "This is good."