Based on recent discussions about Variable Arrays, I have made a draft update to these wiki pages:
Please post any issues or suggestions for improvement that you may have.
Good stuff. Perhaps put more links to related topics, such as where these tokens can be used exactly.
Thanks for your feedback.
Could you give me an example of what you mean?
I'm all for related links, just not sure what you mean by "where these tokens can be used exactly."
Generally I’m suggesting that anything which can be linked, should be linked.
On the Calculate Token page, you’ve linked ‘token’, and you could also link ‘variable’, and the reference in the docs explaining which fields work with calculations, and when it requires a specific selector, or not, like using ‘match’ is required for RegEx.
Perhaps a ‘See Also’ section of links including stuff like links into the docs reference comparison operators, and so on.
I know I’m suggesting adding to the load. I apologize.
Hey Carey,
You could ask Peter for wiki credentials and make these additions yourself. 
-Chris
1 Like
Thanks for the suggestions, CareyB.
I added the link to Variable, but I'm not sure what you mean by the above.
If you'd like to provide the exact text and wiki page, I'll be glad to update.
Or, as Chris says:
https://www.keyboardmaestro.com/documentation/7/variables.html
https://www.keyboardmaestro.com/documentation/7/calculations.html
Perhaps I’m being too pedantic.
Not at all. I finally get your point. The Official Documentation pages are much, much more detailed than the Wiki pages.
Seems to me we should put the entire Doc pages into the Wiki, not just link them, so they can be maintained and added to.
@peternlewis, what do you think?
It’s definitely not clear what should be in the documentation and what should be in the wiki.
One serious problem is that there is only one wiki. There is documentation for each version of Keyboard Maestro. So the wiki either needs to be annotated with each thing that is different for each version (which is especially hard to do when I want to release the next major version and can’t publish the information until after the release), or the documentation need to remain (which is the current state).
I do not have a good answer to this.
IMO, the wiki should always reflect the latest version.
If the user needs help on an old ver, they can refer to the documentation.
Do I remember correctly that you can print the wiki to PDF?
If so, then just before a new ver is released, you can make the PDF and those that continue to use the old ver can refer to it.
Going forward, as we update the wiki for a new version, we can flag the changes. We could even a tag for each version.
After you are preparing for a new release, does it make sense to lock the wiki at some point, then you can make a copy of it to make updates for the new ver?
Not that I know of. That is how the documentation PDF is made, but I don't think there is any way to do that for the wiki, and even if there was it would be very unstructured.
But then how do I do a new release? Part of doing a new release is spending a zillion hours on the documentation to update it for the new version. I cant do that on the wiki for the new version before the new version is released.
OK, how about this:
When you get ready to start updating the documentation for the next ver:
- Lock the current wiki
- Copy the wiki to a new site only you and your team can access
- Update the offline copy as needed
- When you get ready to make the release and publish the new wiki you could:
- Replace the old wiki
OR - Leave the old wiki in place with a different URL reflecting the old ver#
- Publish the new wiki using the same, standard, wiki URL
I would only do this for major versions, like 7, 8, 9 ...
I think we can come up with a flagging scheme that makes it easy flag changes for a new version, even the small updates.
HTH.
I definitely think it’s a good idea to consolidate the documentation. The current issue, if I understand this correctly, is that the documentation is ‘more complete’, and ‘more detailed’, but sometimes out of date.
If you consolidate the documentation into the wiki, which seems sensible in principle, those editing the wiki must annotate to deal with the delta. I’ve seen this before. One updates the wiki by writing the new text, but leaves the old text, and annotates it as to which version it’s germane. It kind of ends up looking like a Word doc with the revision system turned on. (Can you colour text in this wiki?)
If going this route, the maintainer(s) must state how many versions will be covered, and then remove the annotations that have dropped off the bottom of the stack.
The transition sounds like a bit of a bitch, but once you’re done software updates should actually be easier. You could even ‘assign’ page owners for the wiki, I would think.
Sorry Carey, but I really don't like this approach.
IMO, it quickly produces a page that is hard to read, and can be easily be misunderstood.
I've used the Word revision system extensively, and it works great for a short period with a few contributors while the document is in development. Of course, Word offers the feature to show/hide the revisions, so when you just want to read the finished doc, it is easy to do so. But when showing revisions, it can be very tough to follow.
I believe this would also make it much more difficult to update and maintain. Rather than focus on clearly presenting the feature, the author must also worry about where to put changes, and how to mark them.
I would much prefer that the wiki always reflect only the current version, perhaps with simple, unobtrusive flags that indicate updates.
I was more running through it as a suggestion. I agree about the downsides. We agree about the consolidation, though, do we not?
Archive pages for previous versions, as suggested, but link into them when the new KM version comes out, but only if there’s a change. Simpler is better, but linking is key.
I think my point there is that anything which can be linked to something, should be linked. you should be able get to all related nodes from any of the related nodes. No orphans.
If you mean all of the content that is currently in the Official Document should be put into the wiki, then yes, I agree.
This remains problematic unless the documentation is retired because then the text is duplicated and both need changing whenever a change is made.
But that aside, it would be good for the wiki to have as much info as possible, so adding any documentation info to the wiki does make sense.
What would be the next step, then?
I maintain a wiki on my own. At first, coming from a wordpress site, it looked nice. Now I’m facing the fact that wikis are not structured. No tree, no nodes. And no means to make a structured PDF. So, if I had to to this again, I’d choose Help & Manual or something like that.
When I get a chance over the next few days, I'll at least add links to these pages from the wiki.
We have an interesting setup. Some pages in the documentation point to the wiki for more info, and some page in the wiki point to the documentation. So it appears the users/reader need both sources at this time to have the complete documentation.
IMO this drives us to putting everything in the wiki, since it is searchable.
OTOH, having some stand-alone documents, like Getting Started, Installation Guide, etc outside of the wiki, but referenced in the wiki, make sense to me.