Panorama X Documentation Discussion

Panorama X
1

There have been quite a few posts mentioning the Panorama X documentation, so let’s organize this a bit by moving this discussion into it’s own post rather than split up across various topics. I’ll kick off the discussion with a rather long essay with my own thoughts on this topic. As you can see, it’s a topic I give a lot of thought to.

Videos vs. Text

Many of you are now stating that you prefer text to videos. You can save your breath, because I 100% agree with you. When I’m learning new software, I’d much rather read than watch videos, for all the reasons some of you have mentioned. I’m particularly frustrated right now on this issue in regard to RapidWeaver and Apple WWDC videos.

However, I also know that I’m an outlier – I was reading adult books by the time I was in 4th grade and when I took a speed reading class in high school, I read faster at the beginning of the class than anyone else did at the end of the class (and I didn’t get any faster during the course, though I learned some skimming skills). I’ve read over 10,000 books and sometimes I’ve read computer manuals just for fun, without ever using the software described.

I also know that Panorama has had extensive written documentation in the past, and that hasn’t always worked out very well. Right now many of you are telling me “I don’t have time to watch videos”, but in the past the mantra I heard over and over and over was “I don’t have time or patience to read all that documentation”, and I had many, many, many requests for more extensive videos from people that said “I’m more visual, I’d rather watch than read”. This also is an industry trend, many many software packages now are primarily documented with videos (if they have any documentation at all), and even Apple delivers most of their new programming material via WWDC videos.

Also, for some topics I think videos are much more efficient than text. For learning a user interface, I think it’s a lot better to watch a video that actually demonstrates what’s going on rather than reading a bunch of text. That said, I am hoping to incorporate short videos into the help system.

The “gold star” solution would obviously be to have complete versions in both video and text formats, but this stuff isn’t free to create, and it can’t be created instantly. It took hundreds of hours to create the Panorama X videos, and the Panorama 6 documentation took thousands of hours. There are lots of complaints about the lack of Panorama X documentation, and I completely agree with that assessment, but I think there is at least a thousand hours of work in the written material that is already there. There is no way that I can snap my fingers and produce thousands of pages of material (and I don’t think a wiki is going to do that either, see the next section). I am definitely working on more extensive written documentation, but it’s a slow process.

Panorama X Wiki ?

I was going to comment on the idea of a wiki when it first came up a couple of weeks ago but didn’t get around to it. In some ways, the Panorama documentation already is a wiki. Anyone can submit changes, whether corrections or wholesale changes. And I have received somewhere on the order of a thousand submissions, of which over 90% have been incorporated. Some submissions are just spelling errors, the most important have been code fixes in examples. In general, though, no one is writing any lengthy essays, general just a few words changed per submission.

Most of these submissions have come from a less than a dozen people, and about 90% have come from just 3 people. I’m sure you can imagine who they are. I don’t think there is a well of additional people out there that would actually be interested in doing significant work on this. If there was, I would assume that they would have already stepped up. I’d love to be proved wrong on that, though.

By the way – the big three are Gary Yonaites, David Thompson and Michael Kellock. Let’s give them a big round of applause!! If you ever see them in person, be sure to buy them a beer :slight_smile:

The one thing that can’t be done by users right now is create new topics from scratch. But considering the submissions I’m getting, I don’t think there would be much of that even if it was possible. If someone wanted to add new topics, I could come up with a way for them to do it, but I don’t think there is anyone out there that wants to do that. Again, if you want to prove me wrong, I’d love it.

To set up a true Wiki would be a LOT of work. It took quite a bit of work to set up the current submission system, though in the long run that work has repaid itself multiple times over. I also think a true Wiki would require a completely online system, i.e., no local component. Maybe that would be ok.

The bottom line is that I think Panorama X is already capturing at least 95% of the end user help available for working on the documentation.

Panorama X Forum

One other point on this topic is this very forum, which I think is going wonderfully well and is an excellent resource that supplements both the help and videos. There is already a wealth of searchable information on here. One reason I moved to this Discourse forum was because of the greatly improved search vs. the old email based forum. Also, it’s great that it is now so easy to incorporate screenshots into posts.

One thing you may not realize is that this forum is searchable by Google. To search via google, just prefix your search with site:forum.provue.com like this:

Napkin 10-22-16, 3.11.19 PM.png610×506 88 KB

However, I just tried the same search in Discourse itself and I think it did a better job! So try both if you’re having a hard time finding something.

Napkin 10-22-16, 3.13.00 PM.png656×506 90.5 KB

I think Robert nailed it a few months back, “'tis sweet to have this forum”. I just discovered another cool new (to me) feature in the Discourse admin panel today. In fact if I had a complaint about Discourse, it would be the one that many have about Panorama X – insufficient documentation. Sadly the Discourse people don’t think this is a problem, but I definitely do as far as Panorama X goes. It’s not enough to write cool software, you have to make sure that people understand what you’ve done so that they can use it. Otherwise, you might as well not write it in the first place. So in fact I’ll be working some more on the Panorama X documentation this afternoon, let me get back to it. As you can see, I have no shortage of tasks to work on for the indefinite future!

Jim Rea
President, ProVUE Development

P.S. I believe there is a way that this Discourse forum can be linked directly into Panorama Help pages – that would allow any user to easily add questions and comments to individual help pages. So far I haven’t implemented this link because 1) I don’t have the time to set it up right now, and 2) I think if that option was available it might cut down the submissions I’m getting, and for now I’d rather have the submissions so the actual documentation can be updated rather than comments tacked on. But eventually I think I will add this tight linking between the Help and the forum. If you are interested in the details of what I am talking about you can read about it here.

1 Like
2

Followup – one area where the Panorama X documentation is definitely lacking is screen shots. The Panorama 6 documentation includes a lot of screen shots, often several per page. This is a big reason why the Panorama 6 documentation has so many pages. I really believe in the “picture is worth a thousand words” philosophy.

It’s been pretty difficult to add screen shots to the Panorama X help pages, so I haven’t added that many. About 2 weeks ago I made a change that makes it a lot easier for me to add screen shots – now it is very similar to adding screen shots to this forum. So going forward you are going to see a lot more screen shots being added, both in new help pages and in some of the existing pages.

Since this documentation is web based, I’m also planning to include some animated GIF’s, and also some movies.

1 Like
3

I’m intrigued that, after all the earlier comments and complaints about documentation, there hasn’t been a single reply to Jim’s discussion paper. I’m about to make up for that.

I have a theory about documentation. I believe that newcomers to any skill set initially need no more than a user’s guide that gives them the ability to take the first steps and the confidence to explore further. It should be concise, easy to read, easy to understand, loaded with visual examples and sprinkled with hints and insights into the more interesting things to come. Beyond this stage, a well-designed and well-indexed road map to the whole shebang will give the user the opportunity to specialise. I’m not talking about a big user’s guide, just a map - I’ll argue later that the existing Help document already provides much of that map. Nobody needs to know everything about a field of endeavour - but almost everybody needs to know more than just the basics, so give them the basics and a map to the rest.

So how best to achieve this objective for Panorama X? Just over 20 years ago, at the tail-end of that golden age in which every new version of Panorama was accompanied by a hard-copy manual, ProVUE published Panorama 3 Real World Programming. This 200-page, large-format paperback was a gem. It started at “How to boil water” and went on to explain how to use Panorama 3 to carry out very sophisticated tasks. It catered for datasheet-only users as much as for experienced programmers.

I submit that this could well form the basis of a First User’s Guide to Panorama - strip out the complicated stuff, update the rest and you could have the guide I defined in my opening paragraph. It would be great if Jim still has a digital version of Real World Programming but, even if he doesn’t, it’s not a major task to get a copy typist to transcribe the bits we want.

My earlier reference to datasheet-only users is important. A high percentage of Panorama users have no need to progress beyond the datasheet other than to use the occasional simple program, often written and (hopefully) maintained by somebody else. Think of the people who maintain records of school class marks, club memberships, sporting performances, pigeon-racing results (I’m not making this up) and similar stuff. Panorama is a very powerful tool for these folk and they don’t need 5,000 pages of documentation to use it.

The discussion paper raises the possibility of linking the forum to the Help pages and, as I understand the proposal, allowing users to attach comments to the Help topics. In a word - don’t. If I wanted to read 50 comments on a topic, I’d go to Facebook or become a Twit but I have no desire to do either. The Help document is a well-designed resource with a beautifully clean look, excellent cross-referencing and a minimum of dross. Leave it that way. What it does need is more entries that give an explanatory background to major topics. Many such entries are already there but most of them lead to an “Under construction” message. That’s fine - they will emerge in time.

The new-found ability of the Help file to support screen shots and video clips offers the opportunity to improve it immensely. It is the perfect framework on which to build a comprehensive guide to all of Panorama’s features - there need be no limit to the length of an entry. My personal preference is that it be modified so that users can print the contents of a topic directly from the Help file - I hate having to sit at a computer to read a lengthy document.

The Panorama Database Exchange, currently in stasis, is another potential source of help for newbies. Panorama 6.0 has nearly 50 MB of examples but it’s not feasible to contemplate converting them to Panorama X and it’s not worth spending the time to create new ones. The alternative is that experienced users share their databases with the rest of the community - these would range from the very simple to the complex and could serve as boilerplate procedures. A new user would learn a lot from working out how to adapt a generic procedure to suit their specific needs.

I’ll finish with some comments on indexing; the more information you produce, the more you need a high-quality index. Most of the training videos are too long for casual browsing (a few of them run close to 3 hours). They would be more useful and user-friendly in bite-sized clips which cover a single sub-topic. A table of contents would then enable a user to home in on the answer to a specific question. If subdivision of all videos into small clips is too onerous, and I suspect it might be, an index of sub-topics could guide the user to a video title and the run-time location of its treatment in that video.

This forum lends itself perfectly to indexing. Users have been reasonably scrupulous in starting a new thread when appropriate, so forum topic names alone would comprise a rudimentary index (I assume a list could be compiled with little effort) and key words could be extracted to make a more rigorous index. if this latter task is seen to be too time-consuming, topic names could be grouped under 20 or so category headings and the user could do the leg-work. I appreciate that Discourse already has its own in-house search mechanism but User A doesn’t always think of a topic in the same words as User B - better to index topics under as many relevant words as possible. This is no simple task but it doesn’t need Jim’s expertise - a junior clerk could do it - heck, even I could do it.

Don’t hesitate to cut down any of these suggestions - I’m unlikely to cry myself to sleep over it and my prime purpose is to stir up some responses.

4

Which application are you using to create those animated GIFs?

5

It’s called Claquette, it’s in the Mac App Store for $10 as I recall.

6

Is Claquette still your choice?

How about your latest Screen Shot/Grabber/Movie Maker?

7

I still use Claquette occasionally, but now I mostly use ScreenFlow for both videos and animated GIF’s. Of course that’s a lot more expensive than Claquette (and more powerful). I need ScreenFlow anyway for the videos, but if you don’t need videos I probably wouldn’t buy it just for animated GIF’s. (I think at the time this question was first asked ScreenFlow didn’t support animated GIF’s.

8

And what is your favorite for screen shots?

9

I normally just use Command-Shift-Control-4, the built in system tool.

However, most of the screenshots are edited and annotated with a tool called Napkin, which is available on the App store. It’s kind of expensive, $40 the last time I looked. It turned out to be well worth it for me, on a dollar/minute basis for my use it is a bargain. It makes common screen shot editing/annotation tasks super fast, so it’s saved me a ton of time over anything else I’ve seen. But if you’re not doing at least hundreds of screen shots a year, probably not worth it. A downside is that it hasn’t been updated for years – I believe the primary author now works for Apple so I suspect it will never be updated. It still works fine, and probably will continue to since it’s fairly modern, but it would be nice if there were updates, and I definitely have suggestions.

10

Annotation of screenshots is a new built-in feature of macOS Mojave. You use cmd-shift-5 and get an UI that lets you choose selection / screen grabbing and lets you use markup functions on the screenshot, similar to those known from Preview.app .

11

Have you thought of making an offer for it?

13

My answer on that hasn’t changed since the one I gave above (in October 2018):

14

I looked at the Mac App Store - it’s no longer available.

15

You’re right, Napkin is no longer available, but Claquette is. Fortunately Napkin still works on my system.