Plan for Wiki conversion of the documentation

Wiki
1

I’ve made a start at converting the documentation.

My plan is for the wiki documentation section to take over entirely from the old documentation.

Then I will have to make an archive copy of the version 7 documentation section when I release version 8. Not sure yet how I will do that. Then I’ll have to find some way to lock the wiki and create a private wiki that I can modify since I can’t leave the documentation update until the 8.0 release as the documentation takes a significant amount of time.

And it needs to support the PDF, which means it needs to support the Single Page version, but I have that in place already, so it should be doable.

And I will lock a few of the pages so only I can change them (definitely Purchase and Administrative Details, possibly Overview).

So the tedious part is going to be converting the existing docs to the wiki. The docs are generated from a markup document which is akin to Markdown, but with more custom facilities like “CHOOSING{Keyboard_Maestro,Purchase_Keyboard_Maestro}” which expands out to “choosing Purchase Keyboard Maestro from the Keyboard Maestro menu” with the two menu names linked to the menu section of the documentation.

I think I might scrap the Menu section of the documentation, it is mostly tedious and not of much value.

So my plan at the moment is to just work through the documentation and manually translate the stuff as I go (probably using a bunch of macros I create on the fly). If anyone is keen to do some of the translation, you can let me know although we’ll have to be careful to avoid duplicating work and to ensure consistency.

Also I’ll ask all wiki editors to please tread extra softly when editing the documentation - I expect to be asked before doing any significant changes (which is largely true of the wiki too, but much more so in the documentation which is a more formal document. And for the moment, please don’t edit any of the documentation pages until the translation is complete without talking to me first.

2 Likes
2

Awesome! If there’s anything I can do to help, let me know. I don’t mind doing grunt work. If you have an example of what you want, you can throw a section of the docs at me and I can try and match what you’ve got.

I’m kind of passionate about this, so you can count on me wanting to get it just right, meaning just like you want it.

I’ve been holding off on doing any Wiki editing, because I really thought you should put everything in the Wiki, but you weren’t sure, so I thought I’d just wait. Glad to see you ended up agreeing! :stuck_out_tongue:

1 Like
3

OK, I have finished the transfer of the documentation to the wiki at https://wiki.keyboardmaestro.com/Documentation. I would not just yet advise doing any editing on the pages, but I would appreciate anyone who has the time going over it to see if there are any problems with the transfer to the wiki. It is based on a markup conversion from my own markup document, so if there are any systematic problems I can resolve them by reprocessing the source, which is why editing the wiki documentation would be a bad idea now.

After that I’ll write protect the Purchase, Support and Administrative Details section and then we can look at what adjustments need to be made to better integrate it with the wiki (for example there are now to Quick Start documents on the wiki and they are not the same.

The documentation needs to be kept somewhat separate since it needs to be a bit self contained, and it will generate both the Single Page Version and the PDF from there and they need to make sense as independent of the wiki.

After people review it and verify there are not systemic translation issues, then we can look at what to do next. As mentioned before, people will need to use a light touch on the documentation. Also, the documentation includes some extra markup in the form BUTTON{{{xxx}}}, CODE{{{xxx}}} and FILE{{{xxx}}} that visually markup the documentation (they can be used elsewhere on the wiki if desired).

4

Peter, are you saying that you will have both the Wiki you have now, AND a separate wiki/section just for the "Documentation"?

5

I am saying that the Documentation will be on the wiki, but should remain and a cohesive whole. Some people like to “read the documentation”, and that is what the Documentation section of the wiki is:

Going forward I will need to do some work to harmonise the wiki and the Documentation section, particularly those areas where there are versions on both the wiki and the Documentation. Which side of the line they belong on is not always clear, and it may be that I change plans down the track, but the moment I want the Documentation to remain as a cohesive whole, one that you can take the PDF of and read on the plane and end up having a good idea of what Keyboard Maestro is and how it works, but without all the reference material from the wiki.

6

Peter, is there some way for the current wiki to share pages with the Documentation?
IOW, both the wiki and the Documentation refer to the same set of pages, they just use different TOC/master page.

Otherwise, I'm concerned that you will have a very difficult, time-consuming task to maintain both and be consistent. There's an old database rule: As soon as you have the same data in two different places, one of them is wrong.

BTW, something that has always seemed confusing to me is to call the main Keyboard Maestro document "Documentation". Documentation is a term that refers to all documents about a product, which, IMO, would include the Wiki. What do you think about calling it "User's Manual" or "User's Guide", or something similar?

Here's another possible approach: Have a "Getting Started Guide" which, by definition, is brief and limited in scope. Then have the Wiki which provides full documentation of all features.

Thinking out loud, seems like a good organization for the complete Keyboard Maestro documentation might be:

  1. Getting Started Guide
  2. Examples
  3. Video Tutorials (Stairways and user supplied, but organized/curated by Stairways)
  4. Wiki (comprehensive, all features)
  5. Forum (support and user shared macros/plugins)

Just sharing some ideas/thoughts with you. Whatever you decide, I'll be glad to support.

7

The plan is not to have duplicated pages/information on the wiki.

The plan is for the Documentation to be a cohesive whole within the wiki.

So, for example, there are two Quick Start pages, /Quick_Start and /documentation/Quick_Start. My plan is to merge the useful information from both of them and for one of them to be deleted. In this case, I think I will delete the /Quick_Start page and so all the Quick Start will be within the documentation.

This should avoid the issues you describe.

And your point about the naming of it Documentation is definitely valid, but I'm not sure it is compelling - for one thing I dislike the term "User" (there are only two industries that use that term for their customers, Software and Drugs, and I'm not entirely convinced this is just a coincidence ; -). Manual or Guide would work but they are vague by themselves.

Your outline is good, and basically the plan is for 1-4 to be within the wiki where (Video Tutorials) is really just a question of doing it, and (Examples) could be done in many different ways (including the macro category on the forum, a curated section of the wiki, a section of the Documentation (which they are but I will probably remove that section), or some sort of full service web site for getting/using/commenting/rating, etc macros. Currently the macro category on the forum is winning simply because it requires the least amount of work.

8

I don't know why you would dislike "User's Guide" or "User's Manual". It is a very common term, well understood by anyone who uses software, and one or the other has been used by almost every software app I have ever used, both Mac and Windows. Why fight using something everyone understands?

Having said that, do you really need a comprehensive document (by whatever name) that is organized like a book, intended to be read front to back? I don't think I have ever completely read any manual front to back. And I don't know of anyone who has. Have you? :wink:

So, the question is, what is the purpose of such a document?

OTOH, I often do read a short (< 5 pages) Getting Started Guide, provided it does what the name suggests -- help me quickly get started using this thing. :smile:

I think most people today are geared toward searching for what they want. The problem with searching is knowing what terms to search for. So, to me, that suggests that the wiki needs:

  • An Excellent Terms & Definitions Section
  • that lists the major terms the user needs to know to use and work with the basics of Keyboard Maestro
  • Keep it limited in scope so that the user is not overwhelmed, and might actually read through the whole list.
  • Glossary OR Index
  • detailed list of all terms used by Keyboard Maestro.
  • Definitely some overlap with #1, but serves a different purpose.
  • OR maybe call it an Index, with links to the Wiki for each term.
  • Synonyms -- very important
  • These are the key to making search work
  • Particularly important for the less technical, less experienced user
  • Google does this so well, so implicitly, that you never even notice, except that somehow what you were looking for turns up ver often in the top 3 hits.

So, in summary, I'm suggesting that maybe you don't need a comprehensive, book-like document. Instead just:

  • Getting Started Guide
  • Comprehensive Wiki with great search engine

Again, I'm just throwing out ideas for your consideration.

9

I have, but that's not the point. I get asked for it regularly, and there are indeed a lot of people like that, so yes, it is something that I want (not need per se, not much in the way of helping people is necessary, but I try my best to accomodate different people and different learning styles). I don't get the point of the PDF document either, but I am regularly asked for it.

The Documentation also gives a convenient place to put administrative details like how to purchase, how to download, and the license and warranty disclaimers.

I have a quote I like to use myself, "Never make the mistake of assuming you are typical". It's a safe bet that anyone who reads the post is not typical - they are already way off the bell curve on the "paying attention to what is going on with Keyboard Maestro" scale.

The Documentation may head towards being a Getting Started Guide, and calling it a User Manual may well be sensible. But either way it is definitely needed as a single document that can be read "cover to cover" by those folks who want to do that.

Extending and enhancing the glossary/index/terms/synonyms is definitely something that needs doing. The Documentation has a Glossary page, and with the Documentation now being on the wiki, it can be linked more completely with the other information. A Glossary page can also act as a synonym holder, since it can include "See Also" entries (although that may require the Glossary page being sub-linkable, which I doubt it is currently).

10

If you think I am making that assumption, then you would be wrong. :smile:
My statement was based on years of working with a wide variety of users. I got many, many questions that were covered in the User's Manual, often within the first few pages. The high percentage of users either didn't have the time or patience to read the whole manual, or thought they were too smart to need it. Plus, it is just easier to ask someone, or post a question on a forum.

Here is the question I'd pose to you, Peter: Is the percentage of users asking for, or you expect to ask for, a comprehensive User's Guide, including PDF, worth the effort, and worth having a major impact on your documentation plans, worth the time you will have to spend on it?

Maybe here's a way to think about it.
How do most Keyboard Maestro users get their information about Keyboard Maestro?

  1. Reading the comprehensive "Documentation" (User's Guide)
  2. Reading/Searching the Wiki
  3. Reading/Posting questions on the Forum
  4. Other (videos, trial-and-error, etc)

BTW, one thing I really liked was the frequent (daily/weekly) emails I received from you when I first signed up / downloaded KM. Each email was focused and had just the right amount of info for a "daily lesson".

I'll throw something else into the mix here: How about a "Training Guide" ?

The typical User's Guide is very boring, and a challenge to get through. Historically it has been the complete reference to use when you could not intuitively figure out how to do something in the software. The main problem is that it often presented to much information, that was too complex, for the user to absorb at the time (that's one reason I don't think reading it front-to-back makes sense).

But a Training Guide could be like your daily emails, starting slow and getting the user comfortable with the terms and UI before launching into complex macros.

So, here's a new line-up:

  • Getting Started Guide
  • Training Guide
  • Could be linked with Examples & Tutorials below, but provides a more ordered approach to learning KM.
  • For those who want/need a more structured learning method
  • The ideal would be an online, interactive guide, but it could also be made available as a PDF.
  • Wiki (comprehensive, searchable, reference)
  • Examples
  • Video Tutorials
  • Support (Forum)

BONUS: The term "User's Guide" never appears. :smile:

All just more brainstorming. Hope I'm not boring or frustrating you.

11

Here’s an example of something that bothers me:

I’m working on an “Execute an AppleScript” action. I can’t remember the syntax to get a KM variable. So I use the “Help” option. It takes me to this page: https://wiki.keyboardmaestro.com/action/Execute_an_AppleScript

Not really useful. If there was a link to https://www.keyboardmaestro.com/documentation/7/scripting.html, then that would be helpful.

12

The problem is the wiki article you referenced is out of date, or, really, was never brought up to date. Some time ago I wrote a wiki article about scripting, but it now seems to be gone.

The wiki article brought up by the KM Editor Help, should include, at a minimum, these links:
Scripting on OS X Using Keyboard Maestro
AppleScript Tips and Tricks for Keyboard Maestro

Of course, now that you are a wiki editor, you can go change the wiki article in question to read so that it would be more helpful. :smile:

EDIT: Here is the new "Documentation" on wiki page:
documentation:Scripting [Keyboard Maestro Wiki]

13

This is the exact reason I volunteered to be a wiki editor. So when I found something like this, I could fix it, rather than just complain. (Or maybe in addition to?)

The question remains (doesn't it?) of what we're going to link to, as far as the documentation is concerned.

14

If I understand @peternlewis correctly, the "Documentation on Wiki" is to be a standalone thing. I assume that the KM Editor Help will continue to link to the normal wiki. (This term "Documentation" is very confusing to me. It is hard use and write about.)

I think this illustrates the point I was making earlier: Now we have two different wiki articles about AppleScript -- one for the normal wiki, one for the doc-wiki. I don't see how this is going to work.

15

I think it’s OK for the the Help to go to the wiki, as long as there’s a link in the wiki article to whatever page has the details.

16

Maybe. Maybe not.

IMO, the Help wiki needs to be very focused and specific to the action it was linked by.

I don’t want to have to read 3 pages in a full-blown “document” just to find the specifics I need.

The Help wiki needs to be specific, and consistent with the product.
So now, every time a feature changes, you may have to update both the “document” and the wiki.

17

Yeah, I get that. All I’m saying is that, at the minimum, we should have the link in the wiki help page.

You and Peter can duke it out about whether they should be combined or not.

18

No "duking" required. It's a matter of scarce resources and logic.

19

I'm not sure which page, but I did shuffle a bunch of things around related to variables and scripting a while back. I made sure not to lose any info in the process. More shuffling will be needed now the Documentation / User Guide / User Manual / whatever is on the wiki.

The wiki articles can link to the DUGUMW and vice versa. That is fine. Anyone reading the PDF wont be able to follow the links to the reference material, and that is fine too. The primary requirement is you should be able to read through the DUGUMW and have an overview of Keyboard Maestro and how it operates (which, lets face it, is as much as anyone ever gets really).

Yes, I agree, I have work left to do in harmonising them. There are now a bunch of duplicated pages with different content, and I will go through and carefully decide which ones I want where. Likely Scripting will move entirely out of the DUGUMW since it is more reference than initially useful.

Yes, we are slowly adding See Also style links to the wiki pages.

1 Like
20

OK, so I have renamed the documentation to User Manual, and it is now in the manual Namespace.

I merged the two Quick Start articles into the manual’s Quick Start and redirected the old one over to the manual.

There are a bunch of other manual pages I will look at to see which ones should be where and to merge them together with the wiki contact where appropriate:

  • Scripting
  • Tips
  • Troubleshooting
  • Support
  • Glossary

Maybe more.

1 Like