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