Our community is collecting a rich trove of references to external material: language references, tutorials, online tools, applications, resource pages, books, etc. Mentions of these are interspersed with general posts. It can be hard to find a reference even if you vaguely remember where you saw it or what it was called. If you never saw it in the first place you would never know it was there.
I propose that we create a set of Wiki pages to capture and expand on the body of resource material we are collecting.
The document I want to post is page or two of clarifications, and offer to do the work, suggestions plus and a long outline of topics I could think of initially.
This kind of Wiki collection is in the style and intent of the earliest Wikis.
I’ve been thinking the same sort of thing. But here’s what I want to do, on my own, to start.
I’m going to set up a GitHub repository and wiki, and start messing around. Throw some things in it, see what sticks, how I like things, etc. I just want to learn it on my own. Sort of a roll my own prototype, a version 0.1.0, to see how it works, what I like, don’t like, etc.
Once I feel comfortable, and if you (and I) are willing, we can talk about merging our work, starting over, whatever.
I’m giving you this heads-up so you won’t get blind-sided and think “that jerk stole my idea!” Not stealing anything. Just fiddling around.
Done lots of documentation in my life. Never on GitHub. Time to learn! Yahoo!!
PS: I know others here have similar GitHub repositories. If any of you have any thoughts on this, feel free to jump in.
I setup a GitHub repository a year or so ago, but never really used it, mainly because I just didn't have (or take) the time to learn how to use it. About 6 months ago I started using GitHub Gists, which are very easy to use, but also very limited (like no email notifications).
So, funny enough, just two days ago I decided to move back to the Repository.
I just need to go through the tutorial videos so I know what to do, and what is available.
I'm not sure that we should mess with the KM Wiki right now. It is in a state of transition, incorporating the KM documents called "Documentation", which were (are) on a separate web site.
IAC, there are many topics related to KM that are useful to know, but not required to know, like RegEx. The list could be quite large, and trying to maintain such an external resource list could be quite distracting. We already have references to external resources in the KM Wiki at the bottom of each article, where it is appropriate to do so.
Oh, I see what you’re saying. I forgot how the topic started, and in my mind, I had already decided that if there was going to be an external wiki or whatever, and it proved to be useful, that linking to it from the Wiki was the best way to go…
Sorry I got a little distracted. Happens at my age.
I'm going to say what I have to say then drop the subject. I have my own resource collection, and I can harvest resources mentioned in posts.
Your comment directly contradicts the consensus arrived at in [A Thought about the Sites Growing Discussions of Scripting]{A thought about the site's growing discussions of scripting}, where it seemed that everyone — @peterlewis in particular — agreed that anything to do with scripting was fair game for the site.
I don't at all see how [quote="JMichaelTX, post:7, topic:4126"]
We ALREADY have a place for resource links.
[/quote] I don't know where that is, how to find what's there, or add to it.
The purpose of what I wanted to propose was to extract and organize information that is already in posts, or will be in posts in the future, that
aren't really directly relevant to the OP
are scattered all over and difficult to find
would not be something someone would search for if they did
The current Wiki is heavy-handed in that it requires write permission, is tightly constrained, and is being written by a very few people (2?). The original Wiki concept was that all pages were open for everyone to contribute. That is the best way to build a repository of communal resources.
the only top-level table of contents for the Wiki is one that reproduces the KM manual. It never occurred to me until engaging in this discussion that there were pages on other things in the Wiki, such as JavaScript for Automation. I tried something else: there's nothing on GUI Scripting. So it's really hit-or-miss and all based on search guesses.
Besides, sometimes someone wants to come at things not from a known topic but to find out what there is to know: all editors that could be used for scripting in one way or another, or IDEs. It would be good to have all that collected, rather than requiring queries, and it would be good for their to be an obvious pointer to the topic so that people who don't know it's there will see it.
I found one page with a few references to books on it. One page with four books? Consider how many books have been recommended in various posts.
I may be wrong but I don't think there is anything substantial about Swift in the Wiki, and Swift will become increasingly important.
Does anyone know what Xcode can do with AppleScript, if anything, and how?
What about the convenience of assembling reference material in one place. Is it worth saving people the trouble stumbling around looking for Apple's AppleScript Guide? Explaining that the only documentation on JXA is something called "Release Notes" (which sounds like an update, not the documentation itself)? Pointing to Apple videos not everyone know about or how to find? Would it be worth having a list of the top sites everyone goes to, such as MacScripter, for people who are using KM and just getting in to using it for AppleScript?
Would it good to have references to Markdown documentation, tutorials, and examples? It sure would have saved me some trouble and other people time answering my questions. I didn't even know that Discourse accepted full Markdown until recently. (Does everyone know how to tell Discourse what language to use in adding syntax highlighting for a code block?)
What about useful tools such as UI Browser and ScriptLight? What's the best editor for Markdown? For XML? How do you use the Safari debugger for JXA?
Even something as trivial as "which tool do you use for screen capture and markup" would be better collected on a page then sprayed all over posts to which they are not relevant. (I'm not saying that it's not OK to ask these questions in the middle of other posts, what I'm saying is that those posts do not serve as appropriate repositories for knowledge about the topic.)
I have lots more I could say, but I think I've said enough.
There are already entire web sites, forums, discussion groups, GitHub repositories, etc devoted to most if not all of the subjects you mention.
If you feel the need for yet one more resource site, then go build it.
The Keyboard Maestro sites are NOT a primary learning resource for any of these:
AppleScript
JavaScript for Automation (JXA)
Swift
RegEx
Xcode
etc.
even though there is substantial information we share with one another on these topics.
We barely have enough time to maintain the KM Wiki, and respond to questions in the KM forum. I for one, do not have the time, and will not support, some other "resource" site. IMO, that is a huge distraction.
Having a Resource section of the wiki would be fine.
I like @DanThomas’s idea of setting up something on github and working through how it would work and look and then deciding if it was appropriate to be a section of the Keyboard Maestro wiki or better as an independent resource (simply pointed to from the Keyboard Maestro wiki perhaps).
I'm pretty sure I said anything to do with scripting relating to automating was fair game. Scripting in general is a humungous topic, too big for the Keyboard Maestro forum or the Keyboard Maestro wiki. But Scripting relating to either interacting with Keyboard Maestro, or controlling other applications, or those sorts of things are fine. that would generally include almost anything that was traditionally done with AppleScript, but now might be done with JXA, JavaScript in a browser, Swift, etc. But many things done with ruby or perl would not be appropriate (ruby based web server stuff for example, or perl scripts to solve chess problems, or whatever). Don't misunderstand mentions of specific scripting languages either, lots of stuff in Swift would not be appropriate (developing an iOS game for example) and lots of stuff in perl would be (text processing for example). The point is there should be a specific user wanting to accomplish a specific goal that at least tangentially relates to Keyboard Maestro automation.
Anyone is welcome to edit the wiki. There are currently 13 people signed up. I turned off allowing arbitrary signups because there were 3000 (!) automatically created accounts not long after I set up the wiki (I had to write a very impressive Keyboard Maestro macro to delete them all!). So by all means, if you or anyone would like an account to edit the wiki, just let me know. The more the merrier - I would let anyone edit it, but sadly the world is a messed up place to live.
There are two “top level” contents pages on the wiki, the main home page:
(which technically is linked from the first one anyway).
The User Manual has only recently been added to the wiki, and there is still plenty of work for me to do in harmonising the two. But I wish to retain the User Manual as a separate entity for those people who like a single PDF manual of software (not me, but plenty of people do for whatever reason). It also gives me a very explicit place to have the admin details about licenses and such.
I think what you've described is beyond the ability to document. I have no problem with anything in there, but I doubt the server could even hold all the information related to GUI Scripting, IDEs, books, Swift, JXA, AppleScript, Markdown, Discourse, tools, debuggers, etc. But I'm happy to increase the size of the server if someone wants to document all of that, so I have no problem with anyone trying.
Anyone who wants to try can email me for an account on the wiki.
That's fine, but it wouldn't have the dynamic nature of Wiki pages, nor the ability for anyone to easily contribute.
Oh, absolutely do! As it happens, a couple of hours before reading this I posted on the applescript-users mailing list a complaint about Apple's moving their documentation — AppleScript in particular — to HTML format. The main advantage of PDF over structured documentation such as HTML or Wiki pages is that they provide linear search and active indexes. I frequently search the AppleScript manual, for example, for words I know are related to something I can't quite put my finger on well enough to locate in the document myself.
OK, so I think maybe this gets to the heart of where people are missing my point. A page about AppleScript would look something like. Everything on it would be a link, not information, except, optionally, people's comments under each item. If a page like this got too big, it would be split at the next level of the hierarchy. There would be a top level page with topics such as "Languages." Languages would contain links to all the language pages. If at some point the page for a language becomes too large, it would be split with a page like "AppleScript" containing just the next level topics with links to their pages. it's just a resource collection, not the information itself. No examples, paragraphs, discussions, quotes, etc. — just links, basically.
Wow! News to me!! That's great. I must not know how to look around web sites very well, because even knowing that they are there I couldn't find any information about it when logged in. I resorted to a Google search.
So I guess I'll take my references project off to my own Wiki and see how it works out. We should coordinate efforts.
Cool. I did a bunch of searches, what was it, a couple of days ago. That’s how I found out about the wiki.
I got to thinking about it, and as my mother would say, “my eyes are bigger than my stomach”. I’ve got five different projects going on at once, and there’s no way I have time for that now. So, for now, you’re on your own.
I’m looking forward to what you find out. Make sure you keep a log of what you find out. I’m sure there’s a way to do that in the repository. If nothing else, in a Markdown document.
The post is by Jeff Atwood of “Coding Horror” fame, who is also one of the founders of the Discourse software that powers this forum. He talks about how he and the GitHub people (and probably others) kind of forced a standard for Markdown. I found it fascinating, although I didn’t read the entire thing. Still, it’s cool to see how a couple of people can change things in a relatively big way.
Exactly the kind of link I would want on a page bout Markdown, which I think given that Discourse uses Markdown but hides most of it under the Editor GUI, would be an appropriate page for the KM Wiki (or an equivalent personal one).
