I preferred that acronym you came up with. Hysterical. 
Yeah, me too, but I figured that would be a hard sellā¦
1 Like
Sounds good.
Peter, can you please provide some clarity about the āmanualā wiki, and the āstandardā (what do we call it?) wiki?
- Which will contain the comprehensive coverage of KM?
- How do you decide what info goes where?
- Where will links from the KM Editor Action help go to?
- Before you converted the āDocumentationā to the āmanualā wiki, there was much overlap, and many gaps, between it and the āstandardā wiki. How will you deal with these issues?
- We (your wiki editors) have done a lot of customization in the standard wiki. Will this be lost?
- Are you going to note in the wiki article if it reflects something that changed from Ver 6 to Ver 7?
- Will the wiki search search both standard and manual wiki?
- When you finish the merger, with there be any duplication of information?
Peter, et al:
Iāve been giving the wiki/manual orgainzation some more thought, and this idea popped out. So I just want to share it with you, and you can determine if it makes any sense, or not.
Basis Premise: Have just ONE Keyboard Maestro Wiki
with no sub-wikis, or references to āUser Manualā vs āWikiā
So, how does one achieve a āUser Manualā?
Well, what makes a manual a manual, vs just a random collection of topics?
Answer: Organization, as laid out in a Table of Contents (TOC).
So, rather than have a separate namespace for āmanualā, just have one wiki. But, to provide a User Manual view, do this:
- On the Wiki home page, have a major item/link to āGuided View of Keyboard Maestro Features and Usageā (OK, name/title needs work)
- This page, which I will call the āTOCā, would be just that, a Table of Contents just as it might appear in a separate document called a āUser Manualā
- It could be a very detailed TOC, with collapsible headings
- Initially collapsed to a high level, maybe level 2 (chapter headings and sub-headings)
- Provide a collapse all and expand all button
- Make all of the links to open in new tab
- On each page referenced by the TOC, have a āPrevious Pageā and āNext Pageā, and a link to the TOC
- Maybe also have āPrevious Section/Chapterā and āNext Section/Chapterā links
- Make each web page relatively short, no more than, say, the equivalent of 3 printed pages
- All pages of the wiki would be available by search
- On any page opened from search have links for all of the above
- TOC
- Previous/Next Page/Section
I believe this would offer the following benefits:
- Provide a āUser Manualā view and navigation
- Make it very easy for a user to read, āfront-to-backā, a complete user manual
- Provide a comprehensive, searchable wiki
- No dup pages
- Easy to maintain
- Easy for the user to get more information about a topic when they are on any page (using the Prev/Next links)
Does this make sense?
That is the idea.
There is just one wiki. The User Manual is just a sub-section of it designed to create a single cohesive document. The primary thing that requires is strict consistency in the page structure, especially so that the Single Page Version works, which in turn makes the PDF work.
Yes, I want to do this (and the existing documentation has it), but I cannot think of any way to do it such that they are removed from the Single Page Version. I suspect the only way will be some sort of custom plugin and I wasn't overly keen to go that route. But perhaps there is some available dokuwiki plugin that would let those Previous/Next sections be marked up in some way and then deleted from the Single Page Version page.
The wiki contains everything, both the reference material and the User Manual. Wiki search will find everything.
- How do you decide what info goes where?
My main distinction is that if it is about purchasing, installing, starting, marketing or using, Keyboard Maestro per se, then it should be in the User Manual. Reference material, macro library/examples, troubleshooting, FAQ, etc would go elsewhere on the wiki. But I am still in the process of clarifying this as I go through the documen, er, User Manual.
- Where will links from the KM Editor Action help go to?
Wherever the information lives, which will be on the wiki somewhere. As far as I can see, most of them would not go into the User Manual, although the Quick Start would be an exception to that for example.
- Before you converted the "Documentation" to the "manual" wiki, there was much overlap, and many gaps, between it and the "standard" wiki. How will you deal with these issues?
By going through and harmonising it like I did with the Quick Start. Some pages in the User Manual will be like the Macro Triggers page - it will have some small amount of (duplicated) information, but mostly refer to the reference pages.
For some things, there is no clear distinction as to whether it is reference or User Manual. For example, the Glossary. Probably I'll leave that in the User Manual so it is available as an initial learning resource.
From the standpoint of the wiki as a whole, it doesn't really matter whether the information is in the User Manual or not since it is all part of the wiki. Mostly the information should not be duplicated (so there should not be a /Glossary and /manual/Glossary), but which one it is is just a decision based on whether I think it should be in the User Manual.
- We (your wiki editors) have done a lot of customization in the standard wiki. Will this be lost?
No. Or I certainly hope not. Just like with the Quick Start, which gained a lot from the editing that had been done to it on the wiki, I will merge the two parts together. But the intention is that any work that has already been done in generating extra information is retained.
- Are you going to note in the wiki article if it reflects something that changed from Ver 6 to Ver 7?
Generally, yes. The User Manual should be related to the current version, and I will likely archive that in some form when 8 is released. So a user of an older version can refer to the User Manual for the version that they are using. And on the wiki, where something relates to a new feature, that can be indicated with something like "(v7.1+)".
- Will the wiki search search both standard and manual wiki?
Yes, it's all one big wiki, the manual section is just a subset with a slightly stricter structure designed to generate a single book-like document.
- When you finish the merger, with there be any duplication of information?
Hopefully not much, no. The basic idea of what a trigger is might be in two places, for example, but most of the information should be in one unique place.
Some of that is quite challenging and that has nothing to do with User Manual. For example, accessing variable via scripting. Which document should that be in? Variables? AppleScript? Scripting? Execute Application action? And that is just on the reference side, add to that that there will quite possibly be Scripting and Variables sections in the manual, and there is likely to be some overlap in places. The trick is always to minimise that - but a wiki is not a database, it can't all be done by references. A database might have a document on AppleScript referencing of Variables which is then references from all of the other pages. And maybe that can be done (using inclusion on each of the pages), but that tends to be somewhat tricky to do. Not impossible though with careful planning. Otherwise just lots of See Also's work, though the reader can get frustrated with that too.