As you hopefully know, Jack and I put a fair amount of effort into our documentation. Jack writes original material and update notes, I take the straight text and turn it into pretty HTML files with indexing, table of contents, links, pictures, etc.
For the past decade plus, we've been using a tool called "Doc To Help." It does most of the heavy lifting with regard to page layout, formatting and HTML code, index and table of contents building, etc., and we feel it has served us well. But it's getting old* and an expensive update is required soon, so we're looking around a bit to see if there are any better tools/systems out there.
We'd like to ask for some input from the A-Shell Community, which I imagine falling into two categories.
1. Comments about our existing documentation: things you like, things you don't like, features/aspects that you use a lot; things you don't use, think are a waste of time, problems you've had finding things, etc. All comments—both positive and negative—will be helpful, since they will provide us with some criteria by which we can choose our new (or continue with old) direction in documentation.
2. Samples. Most A-Shell programmer/developers use other computer tools in addition to A-Shell, and those tools or programs or systems have documentation. Please send us screen shots or descriptions of your favorite documentation. This might be from printers, other hardware, languages and compilers, word processors, analytical tools, network management suites, etc. What I mean to say is, don't limit your thinking to languages or systems; good documentation can be anywhere.
Any input that you can provide would be much appreciated. You can post things here or send them directly to me (ty@m....com.). Thanks.
Ty - i think the documentation is superb (even though some postings may elude otherwise!)
What you don't see is how many times we all goto the documentation and don't post inquiries. Perhaps you should add a question after a user does a search and ask "Did this solve your problem?" like some other online docs do... that way you can see all the usage (But please don't do that its super annonoying!)
Sorry i have nothing positive to add other than i appreciate all the hard work it is to keep all the microsabio documentation, instructions easy to navigate and up to date.
Thanks for the update comments, gentlemen (and Herman too). It's good to know that our efforts with documentation are meeting your needs. And we appreciate the kind words.
I agree with you, Stephen. The best system would be one where the relevant documentation and answer is displayed on the screen just as you're trying to think of how to ask the question.
BUT, we weren't so much looking for compliments—though they're nice—as we were looking for ideas and other documentation formats. We're not intending to change the organization or depth of the documentation—all the words, chapters, topics, index entries, table of contents, etc., will stay the same. But we feel we need to find a different tool to build the documentation from our source files. If we could see some documentation formats that other people like, then we can track down the tool(s) they're using and evaluate them.
So please keep your eyes open for other doc formats, and let us know if you see some you like. Thanks.
Actually, I like the current format better than most other documentation. It's easy to read, contains helpful links, has useful examples, and includes very good search and index tools. Much other doc I've encountered contains tons of useful info but is written so densely that it requires serious study to understand. Each description heavily employs technical terms which leads to a nearly unending cycle of reading about term A to understand term B to understand term C, etc. Plus the denseness hides a lot of important, but unemphasized detail that can be easily overlooked.
The only improvement I would suggest for the A-Shell docs are more examples where possible.
Ty - i think we were all replying to your sub-section "A" below:
1. Comments about our existing documentation: things you like, things you don't like, features/aspects that you use a lot; things you don't use, think are a waste of time, problems you've had finding things, etc. All comments—both positive and negative—will be helpful, since they will provide us with some criteria by which we can choose our new (or continue with old) direction in documentation.
With that being said, from my perspective, and others, the "If it ain't broke don't fix it" mantra seems to apply.
Otherwise, i don't have significant positive experience with other documentation that i would even use as a reference point.
There are 8 or so separate manuals for various reasons. I would like to see one macro library with a table of contents of all available libraries. Then it could branch out into each specific sub-library. I would like search to search ALL libraries/documentation guides for matches. I would also like to include the "Development History" as part of the main library and search function. This would allow me to search all reference guides at once when looking for a solution. Often times the solution could be parsed out over several different guides, and currently there is no intelligent way to see everything at the same time.
I think I understand what's going on here with your latest idea/suggestion/request, Frank.
I suspect Jack contacted you recently and said something to the effect of, "Ty's driving me crazy with documentation schemes, sales figures, invoicing details and all manner of things. I can't make busy work for him because he'll figure out what I'm up to, but he probably wouldn't suspect you. Do you suppose you could come up with some big project to keep him busy and out of my hair for a couple months?"
This is what happened, isn't it? I'm onto your wily schemes, Frank.
Ha! It didn't work. Thanks to a variety of factors, only about 98% of which are luck, putting together an "A-Shell Reference Plus" was a fairly simple matter.
All in one document are now: The A-Shell Reference plus the documentation for ATE, PDFX, ATS, ASQL, AshLPD and Development History.
We don't know at this point if this "all in one" approach is going to helpful/useful to anybody but Frank, and therefore we'd appreciate some feedback.
So please, if it's not too much trouble, bookmark and start using the "Plus" version of the A-Shell Reference and post your comments here over the coming weeks/months about whether you find it more or less helpful.
Hey team, we have some news on the documentation front.
We looked at several new tools for creating our documentation, and came up with one that looks like a winner. We don't know for sure that we're going to switch, but there's a good chance we will. From what we can tell, and with few exceptions, the new system generates nearly the same output as the old/existing system, but offers various advantages to us the writers/users.
So we've posted the new version, and would like everybody to use it instead of our regular version. If you can, please use this copy of the A-Shell Reference, and let us know what you think. We have already dissected the index and search functions, and we know about some broken links, so comments on them are not needed. But input on all other subjects--things you like and things you don't--is very welcome.
We appear to have lost the input box when searching via the Index. This means that the only way of finding any results is to scroll to see if there is a relevant entry. Not the end of the world, but it would be useful to be able to enter text and either get taken to the nearest location, or have a matching subset returned. I suspect that the same wildcard option that we now have for the more general search facility would be even more useful.
Hi Stuart, thanks for feedback. We definitely have some problems with the new doc's index and search functions--namely, those you mention. I really like our current index system, where you type a letter "s" and all the "s" entries appear, then you type "a" and all the "sa" entries appear, etc. The new system, as you saw, doesn't behave that way, and we're not thrilled with the way it does behave. As you say, scrolling down the list is not the end of the world. But the other method is quite superior, we think. If and when we give the new doc a good workout, and we think it's going to work well for us, then I'm going to have a talk with the developers of the new system and see if they would be willing to implement the "search by letter" function. I don't know if you noticed but the "search" function is also a little deficient, in that you can't search for phrases. If you enter "infld parameters," search replies with all the entries that match "infld" and all the entries that match "parameters,"--which is essentially worthless. The two deficiencies, index and search, will likely be deal-breakers for us--we won't go with the new system unless those things can be "fixed." Thanks again for feedback.
One of the things touted about documentation systems these days is what they call "responsive" designs. A responsive design is one that responds automatically to different sized screens, and rearranges or eliminates various screen elements so as to best fit on the size of device you are using.
That's a big deal these days, because lots of people read documents on tablets and phones which have relatively small screens.
However, we don't think that really applies to A-Shell developers, all of whom are using big screens to do their coding, testing and therefore A-Shell documentation reading.
Is that right?
In other words, we're asking the question of you, faithful reader: Do you read A-Shell docs on your phone? iPad or other tablet? Or anything other than a relative large screen?
One of the things missing from our current documentation system, and something that unfortunately is not likely to change, is the lack of a good feedback system. As you may or may not know, some doc systems have built-in feedback functions, where the reader can write comments and they are either fed back to the authors or shared with the reading community. We don't have that, although I would like to.
BUT, we do have a fast and convenient way for you to comment the tell us about errors, omissions, mistakes, additional info, etc. At the top right corner of every page is a little Email icon, like this:
[img]http://[/img]
If you click on that icon, a new email message will pop up that is addressed to us, that has the name of the current topic as the email subject, and that includes a link to the page in question. All you have to write is, "Hey Ty, this page is missing xyz" or whatever, and hit <send>.
We're always interested in feedback regarding the docs--corrections, ideas, improvements, additional material, miscellaneous comments--so please use that option whenever applicable.
One of my biggest pet peeves is the "dumbing down" of applications for tablets/phones. Can't speak for the masses but i don't plan on coding or debugging programs on my phone, ergo, no need to have features that turn on/off based on screen size. For me, cram as much detail on the screen as possible, let me parse it out. (one of the things i disliked about the new help system was it's "tablet or web" front end)
As for user feedback, i thought thats what this forum was for??!
I have on rare occasions viewed A-Shell documentation on my iPhone and iPad. However, I'd be fine if you stopped supporting that feature or weren't concerned about it. Thanks for pointing out the email icon which will simplify the reporting of documentation errors.
(But please don't do that its super annonoying!)
