for the next version 5.5 I have decided that I'm going to focus on xplorer2 documentation
I've been rewriting xplorer2 help file from scratch, and here's a sample of what I've done.
https://www.zabkat.com/newhelp.htm
It is more detailed (hopefully not TOO verbose), and explains how things are done -- and it is up to date for all the recent major UI changes.
What do you think?
v5.5 progress report
Moderators: fgagnon, nikos, Site Mods
Re: v5.5 progress report
You're probably going to yell at me for this, but the image numbering is off kilter - because it is not uniform. Well, IMO anyway.
Considering images with numbers only:
Suggestion - could you move the numbers to the side, and use lines and arrows to the objects they are trying to highlight? That was you could keep the logical order in the prose, and yet also keep a logical (and standard) order to the numerical values (top to bottom makes most send, I suppose) and then it would be a lot easier to find stuff in the images.
Of course, as you probably know by now about me, I won't really be offended if you don't decide to change the image numbering - it's just a suggestion. I feel it is the better of my suggestions, as the alternate is for you to break down larger images to much smaller images and place them inline with each point - something I know you really do not want to do lol.
Considering images with numbers only:
- First image you're jumping all around
- Second image is logical (top to bottom)
- Third image is logical (left to right - yes, I know this is not logical for RTL-based-language users, I did say IMO above
) - Fourth image is reverse (bottom to top)
- Fifth image is almost logical, and close enough to get away with it
- Sixth image is getting a bit crazy again
- Seventh image is not as janky as last, bu definitely not a smooth as second or third.
Suggestion - could you move the numbers to the side, and use lines and arrows to the objects they are trying to highlight? That was you could keep the logical order in the prose, and yet also keep a logical (and standard) order to the numerical values (top to bottom makes most send, I suppose) and then it would be a lot easier to find stuff in the images.
Of course, as you probably know by now about me, I won't really be offended if you don't decide to change the image numbering - it's just a suggestion. I feel it is the better of my suggestions, as the alternate is for you to break down larger images to much smaller images and place them inline with each point - something I know you really do not want to do lol.
Re: v5.5 progress report
if image numbering is the only problem, then I'm doing a good job 
Re: v5.5 progress report
Glad to hear this. It will be nice to have updated documentation. A couple of quick thoughts about the sample.
The help file seems very linear to me, visually. It is hard to know where one section stops and another begins. There is no strong typography to make the structure clear, at a glance. With scrutiny, you can detect changes in font sizes depending on the heading level, but as you scroll up and down the long document the different sizes, which don't differ by much, don't retain their structural meaning. Every now and then you encounter a long horizontal line, but this doesn't suggest the major structural division that it represents. At a minimum, I think readability would benefit by some major, major break at each of the first-level sections listed in the table of contents. Perhaps this might even be a link to a new page for each of these, but of that I am not certain. To sum up: you can get lost as you scroll the large document -- where am i? what is going on here? -- and visual structure would help.
This also means you need a quick way to get back to the index or table of contents. And maybe the table of contents should be the absolutely top item, and how-to-use-the-guide the first section in it.
If major sections were separate pages, then I'd find it easy to have several browser tabs open to several sections, and know where I was as I changed between them. If I have to duplicate an open tab, open at some place in a very long file, then it is less clear to me as I flip from tab to tab where I am.
Not at all sure what the best way to present this info is, but I do report that the long file leaves me searching and floundering a lot when I go to your help info.
Next, please (please please please) never (never never never) put anything on the page that blinks or flashes. I can't read any of your nice dense text if something is flashing on the screen. The distraction ruins concentration and thought and pondering. I'm not sure how to illustrate what you are trying to show, what mechanism would wourk, but I (meaning me personally) am sure that blinking images is not the right one.
Not quite sure what the @@@ markers mean (likely a flag for work in progress), but the places currently marked with them seem to be the more technical areas that I'd likely be consulting. Hope that info would be as accessible as all the other.
Anyway, I look forward to the new help as it becomes available.
The help file seems very linear to me, visually. It is hard to know where one section stops and another begins. There is no strong typography to make the structure clear, at a glance. With scrutiny, you can detect changes in font sizes depending on the heading level, but as you scroll up and down the long document the different sizes, which don't differ by much, don't retain their structural meaning. Every now and then you encounter a long horizontal line, but this doesn't suggest the major structural division that it represents. At a minimum, I think readability would benefit by some major, major break at each of the first-level sections listed in the table of contents. Perhaps this might even be a link to a new page for each of these, but of that I am not certain. To sum up: you can get lost as you scroll the large document -- where am i? what is going on here? -- and visual structure would help.
This also means you need a quick way to get back to the index or table of contents. And maybe the table of contents should be the absolutely top item, and how-to-use-the-guide the first section in it.
If major sections were separate pages, then I'd find it easy to have several browser tabs open to several sections, and know where I was as I changed between them. If I have to duplicate an open tab, open at some place in a very long file, then it is less clear to me as I flip from tab to tab where I am.
Not at all sure what the best way to present this info is, but I do report that the long file leaves me searching and floundering a lot when I go to your help info.
Next, please (please please please) never (never never never) put anything on the page that blinks or flashes. I can't read any of your nice dense text if something is flashing on the screen. The distraction ruins concentration and thought and pondering. I'm not sure how to illustrate what you are trying to show, what mechanism would wourk, but I (meaning me personally) am sure that blinking images is not the right one.
Not quite sure what the @@@ markers mean (likely a flag for work in progress), but the places currently marked with them seem to be the more technical areas that I'd likely be consulting. Hope that info would be as accessible as all the other.
Anyway, I look forward to the new help as it becomes available.
Re: v5.5 progress report
thanks for the feedback
I will put more space around major sections, and perhaps something like the section back/forward buttons (see your old documentation with F1, is that what you mean?)
ps @@@ are markers I put for work to be done
I will put more space around major sections, and perhaps something like the section back/forward buttons (see your old documentation with F1, is that what you mean?)
ps @@@ are markers I put for work to be done
Re: v5.5 progress report
The current ("old") F1 help does have much better visual punctuation than the sample. The section breaks are clearer, and the font sizes seem punchier and more distinct. The tinted background also helps a lot to make it easier to read. In books, each chapter starts on a new page, and something that strong would be helpful. How you achieve this in html, with one long linear file, I don't know.
The section back-top-forward buttons are helpful, but the come onto the screen only every so often as you scroll. Something like that that was static might be better, but then it might be regarded as screen clutter. But if it were there, then I could get from place to place with two keystrokes (TOC and specific section), making it much easier to jump back and forth while doing some kind of research.
The section back-top-forward buttons are helpful, but the come onto the screen only every so often as you scroll. Something like that that was static might be better, but then it might be regarded as screen clutter. But if it were there, then I could get from place to place with two keystrokes (TOC and specific section), making it much easier to jump back and forth while doing some kind of research.
Re: v5.5 progress report
I assumed that you planed on making the new one more like the old one, with the links, plus navigation at the bottom, etc.
https://www.zabkat.com/x2h_0.htm
Though the local doc is a lot harder to discern page and section transitions on account of the continuous scrolling of the document. I think the last time I opened that was 3 years ago? lol - I had forgotten how it looked.
https://www.zabkat.com/x2h_0.htm
Though the local doc is a lot harder to discern page and section transitions on account of the continuous scrolling of the document. I think the last time I opened that was 3 years ago? lol - I had forgotten how it looked.
Re: v5.5 progress report
to be honest, nowadays to find things, I don't use the TOC but the find command!
Re: v5.5 progress report
Only works if you know what you're looking for.
The manual is not just for established users, though, is it?
The manual is not just for established users, though, is it?