A note to people providing documentation on the internet.
Please provide your documentation in one big HTML page.
I've recently had the misfortune to try and learn and configure a new piece of software for our network. It's documentation is available online as a) a massive collection of small HTML pages, or b) one big PDF.
Both of these are horrible, in their own delightfully unique ways.
The collection of small HTML pages sucks because it's impossible to search for anything, and it's hard to scroll back a few pages to that thing you read 5 minutes ago, to re-read it in the light of some new information. If I want to search for a phrase, I want to be able to just hit Ctrl+F (or "/") and then next/back through everything for all its occurrences, where I can see the full context of every hit. Also, going back and forward through lots of small pages is a pain. First, it's much slower to go "back" through 10 different HTML pages than it is to scroll up 10 pages in the current window. Second, the pages often aren't quite small enough to fit in a window by themselves, so after going back each page you have to scroll each page vertically anyway to scan the text. Third, when browsing the help, I sometimes click the "previous page" link on a page (rather than the "back" button on my browser), which means that my browser history isn't linear. That means that some clicks of the "back" button on my browser will take me forward in the documentation, which is not what I want. Fourth, I could stick entirely to the "previous page"/"next page" links on the pages themselves, except they're typically at the bottom of the page, which means that they're in a different position on every page, because the pages are all different lengths. So every time I want to change page, I first have to *find* the button I want with the mouse, which is slow. That's assuming the "previous page"/"next page" links are always there, as it's the case with some documentation that those links only go to the end of the chapter, and you have to find a different button to go to the next chapter!
The big PDF sucks, because I can't just move and resize the window so it's adjacent to another window where I'm trying things out. Well, I can, but because it's a PDF with a built-in "page size", the PDF viewer is either set to "zoom to window height/width", or "fixed zoom".
If it's "zoom to window", the content grows or shrinks to the point where the font size is too small/fuzzy to read (the same size-on-screen small font is generally much fuzzier in a pre-rendered PDF than it is when rendered "live" in a browser) or so large that not much information is actually displayed on screen. So every time I move the window I have to muck about with zoom settings which is a giant headache. If it's "fixed zoom", then the content either ends up too wide for the window, meaning I have to scroll horizontally (ugh!) to read it, or it's too narrow for the window, resulting in wasted space, and less documentation (and therefore less context) on the screen than would be possible otherwise.
Please, give me one big HTML page. Something that reflows to my window, which I can flick through forward and backwards with complete ease, and search.
I've recently had the misfortune to try and learn and configure a new piece of software for our network. It's documentation is available online as a) a massive collection of small HTML pages, or b) one big PDF.
Both of these are horrible, in their own delightfully unique ways.
The collection of small HTML pages sucks because it's impossible to search for anything, and it's hard to scroll back a few pages to that thing you read 5 minutes ago, to re-read it in the light of some new information. If I want to search for a phrase, I want to be able to just hit Ctrl+F (or "/") and then next/back through everything for all its occurrences, where I can see the full context of every hit. Also, going back and forward through lots of small pages is a pain. First, it's much slower to go "back" through 10 different HTML pages than it is to scroll up 10 pages in the current window. Second, the pages often aren't quite small enough to fit in a window by themselves, so after going back each page you have to scroll each page vertically anyway to scan the text. Third, when browsing the help, I sometimes click the "previous page" link on a page (rather than the "back" button on my browser), which means that my browser history isn't linear. That means that some clicks of the "back" button on my browser will take me forward in the documentation, which is not what I want. Fourth, I could stick entirely to the "previous page"/"next page" links on the pages themselves, except they're typically at the bottom of the page, which means that they're in a different position on every page, because the pages are all different lengths. So every time I want to change page, I first have to *find* the button I want with the mouse, which is slow. That's assuming the "previous page"/"next page" links are always there, as it's the case with some documentation that those links only go to the end of the chapter, and you have to find a different button to go to the next chapter!
The big PDF sucks, because I can't just move and resize the window so it's adjacent to another window where I'm trying things out. Well, I can, but because it's a PDF with a built-in "page size", the PDF viewer is either set to "zoom to window height/width", or "fixed zoom".
If it's "zoom to window", the content grows or shrinks to the point where the font size is too small/fuzzy to read (the same size-on-screen small font is generally much fuzzier in a pre-rendered PDF than it is when rendered "live" in a browser) or so large that not much information is actually displayed on screen. So every time I move the window I have to muck about with zoom settings which is a giant headache. If it's "fixed zoom", then the content either ends up too wide for the window, meaning I have to scroll horizontally (ugh!) to read it, or it's too narrow for the window, resulting in wasted space, and less documentation (and therefore less context) on the screen than would be possible otherwise.
Please, give me one big HTML page. Something that reflows to my window, which I can flick through forward and backwards with complete ease, and search.