One of my pet peeves with Rhino documentation is that practically none of it follows the age-old technical manual convention of including publishing dates, revision dates, version numbers, change bars, etc. used by military and large companies worldwide. Maybe I’m old fashioned, but the current McNeel practice of issuing documentation willy-nilly whenever the mood strikes and never showing a publishing date is pretty annoying. Especially months and years down the line when I go to refer to a piece of documentation and have no clue whether it coincides to the latest version, or whether it is the same old one that’s several years old and never updated.
Oh, well. At least they’ve come around to putting version numbers and release dates in standardized, easily accessible places on all the software. They have, haven’t they? Core Rhino, anyway.
That’s a very good point. @margaret - can we add publication or last modified date to the bottom of the help pages? I am often frustrated when I land on undated blog posts. If the info is old, I look for a second opinion - old information is sometimes still good, but it’s a good clue that it might be suspect.
Updates are not quite willy-nilly; The Help is normally updated when there is a service release.
So, in order to do this right, I need to know what problem this solves for you.
I normally put the publication date on the Home page only. Do you need it on every page? Do you need this to be the date the actual page was changed, or is when a whole help project is uploaded good enough.
Is a publication date enough, or do I have to come up with some kind of versioning number system?
What is posted on the web is always, always, always the latest version, updated to the best of our ability.The downloadable version is possibly being discontinued for Rhino 6. Or possibly it could be an optional download.
Change bars? Really? Aww… Do I hafta? This adds a whole new level of difficulty to updating.
What are you looking at that you have to guess if it is the latest version or an old one? Are you comparing the information in the shipping .chm file and the web version? It’s true that updated .chm files did only happened with service releases and updates stopped a couple of versions back because the changes were so minor. They weren’t delivered with service release downloads, only with new CD downloads.
So… what is it you really need to know? I’ll do my best to accommodate it.
I’m thinking not so much of Rhino itself but of all the material for all the products. Even the McNeel supported plugins.
The best documentation I’m familiar with does both. I think that for electronic publications the home page should show a date for the most recent full update and the date of latest revision. Each page or at least each individual topic (revisable chunk) should have a footnoted date showing the most recent revision. In fact, a list of all revisions after the full update. The next time a full update is made, each page or topic should carry that date. I also think that if a revision is made in conjunction with a service release that information should be included in the footnote.
BTW, I have seen some McNeel plugin documentation that has no date of any kind anywhere.
At least in the case of YouTube and Vimeo postings the user can infer something (with a low degree of significance) from the posting date.
The main thing, as I see it, is twofold: to have an explicit tie over time between a document and what it’s documenting, and to have some sense of change history so that the user can locate him/herself in the continuum of information. When the system is implicit and not well communicated, being mentioned in easily missed parts of the document or not at all, the user’s sense of security that he understands how the material he’s reading applies is not very firm.
As I said, I’m thinking across the spectrum of McNeel products. I think that as you consider this issues and any changes it would be good to keep this in mind. If you can devise a set of standards and guidelines to apply to everyone who has a product under the McNeel banner and a policy to enforce them your users will benefit greatly.
The information conveyed by change bars? Yes. They sure make it easy for me to quickly identify and absorb the changed info I need. Once one has an intimate familiarity with the basic material, skimming for changes is very easy. On the other hand, I’m an old guy. Maybe there’s better ways to do it now. Better, not just different.
I always assumed that documentation software had tools to do this stuff automatically or with minimal author intervention. Am I wrong? Or are you using the wrong software?
Isn’t all of that information already on the wiki pages. At the bottom, there is who lasted edited and when. On the side, there is a link to old versions. If you click the link, you can compare versions to see the changes.