Why I like reading software manuals in .PDF form:

[Grant Robertson]

1. When a manual is in .PDF form, I can simply read one page after another, till I get to the end, and know I have read the entire manual. HTML-based manuals force me to navigate a maze of links, hoping beyond hope that I have successfully found every page. Even with a navigation bar on the side, one cannot be sure that every single page is linked to in said navigation bar. Many, many HTML-based manuals end up with sub-pages that can only be found via an obscure link, buried in a paragraph somewhere. So, you are forced to click every link you see, out of fear of missing out. This makes reading a manual kind of exhausting.
2. In a .PDF, I can annotate the document as I see fit. I can highlight important parts. I can insert any questions I may have while reading (even when away from my main computer). Then, I can go back and try to answer those questions when I am either at my main computer or when I am online. Plus, sometimes you just want to insert a question and then keep reading. With HTML-based help, you have to use a separate method to keep track of all these notes and questions. It then becomes extra tedious to keep track of which note or question is about which part of the manual. 
3. I can synchronize a .PDF manual (along with all those annotations) between different devices, simply by storing it in some cloud-based service. Yes, I can sometimes save "favorites" or "bookmarks" in an HTML-based help system, but those can never be synchronized between all my devices. So, if I want to make use of that feature, I am forced to always read said help on a single device.

Without these abilities, reading HTML-based help can become extremely frustrating. Especially when said "help" glosses over most of the actual detail of how to use the program. As a former network manager, and a former technical writer, with a degree in Computer Science and Education, I can definitely tell the difference between me simply not being able to understand something and just poor documentation.

 

I do have the tools available to convert existing HTML-based manuals to PDF. But it can be a tedious and error prone process. And the whole process must be repeated each time the HTML-based manual is updated. It is always far better to just start from the source files and use a reliable utility to produce the .PDF version of the document. Usually, the same tool that generated the HTML-based manual has a feature to generate a .PDF file as well. So there is often no real excuse for a company to neglect doing this.

Sometimes it feels as if software companies rely solely on HTML-based documentation just so they never have to worry about users working from an outdated copy of the manual. But I also feel that this is a bit of a cop-out.

[Grant Robertson]

Alrighty! I just tried using Adobe Acrobat Pro XI to capture the HTML-help (from the Affinity site) to a .PDF file. Unfortunately, no matter how I attempt to do so, regardless of which URL I give to Acrobat as its starting point, the only thing I get is the first (title) page of the help/manual. 

I also tried using the "Print Page" feature of the HTML-based help (at the bottom of the navigation bar), and simply print that to .PDF. While it does print the page appropriately, there are additional problems with that technique: 

1. I would have to print each page individually, then combine them all together as one .PDF. That's a lot of pages.
2. Any links on that "printed" page go back to the Affinity site. While Acrobat Pro has a feature where you can right-click on a link in a .PDF file and choose "Append to document," the problem from the first paragraph rears its head and all you get is the title page. Therefore, the only way to get links in the document to actually jump to the correct page within the document is to (insanely) tediously fix each and every link manually. 

I have a "fall-back" mode, wherein I keep my notes in Microsoft OneNote, then copy snippets of text from a web page and put my comments under that. I even have a set of AutoHotKey macros that will quickly grab the quote from the web page, along with a "link to selected text," then paste that quote into OneNote and insert a hyperlink back to the location of the quote on the original website. However, because of the way that these HTML help pages are generated and fed out over the internet, it is impossible to use the "link to selected text" feature of the Chrome browser, and so my links can only go to the whole page itself. While this is "adequate" it still generates friction when I am trying to reference back to the original text. Plus, I will have copied and pasted almost every sentence of the entire manual by the time I am finished. Yes, I have questions about almost every single one. 

I know, a lot of people will ask me why I would bother to go to all this trouble. Because I like to truly know how my software actually works. I don't like to be guessing my way through everything all the time. And, I like to be able to go back to an authoritative manual for reference when I forget things, and not have to figure them all out from the beginning. Plus, I hope to (eventually) be making YouTube videos about these products, and maybe even write a book. I am not satisfied with just dinking around with a feature for a few minutes and then churning out yet another video that glosses over all the details, or is utterly incorrect (while sounding authoritative). I am hoping there will be an audience for truly authoritative, detailed (while still being as concise as possible), accurate, well-researched videos. I am a retired network manager / technical writer, with a degree in Computer Science and Education. I know the difference between good and bad documentation and training videos. Unfortunately, almost everything I see is in the latter category, and I would like to try to fix that.

[deeds]

100% Agreed!

There's another (implicit) benefit of PDF Manuals... providing one forces the software maker to think about and articulate their product's features in a linear and complete manner. This, quite surely, benefits everyone; including the software maker, as it will more easily reveal workflow problems and excess user interactions for any and all operations.

[dcr]

I also like to be able to print PDF manuals.  That way, instead of having to flip back and forth between the application and the documentation, or having one on the computer and another on the iPad, I can have the printed PDF on my desk and flip to the necessary page without leaving the application.

And that means it's beneficial not only to have a PDF but if they also design the PDF with large enough margins to accommodate a 3-hole punch so I can keep it in a 3-ring binder.  (Also means sections can be updated as needed.)  Sure, you can shrink it, but if the text is small to begin with, then you end up with even smaller text in order to get decent margins.

And, it's generally much easier to print PDF documentation than HTML documentation.  Too many times the screen view and print view for HTML are different or you end up with images that are too large or misplaced.

Also, keep video content separate.  Or, if there is video, also have what is in the video transcribed into text along with screenshots where needed.  Nothing worse than printing a PDF manual only to later find some of the instructions were embedded in video.  That may be okay if you're viewing the PDF on an electronic device but useless if you print it.

Additionally, in the case of specific features, any examples or tutorials should not assume you've read the manual from start to finish.  Sometimes, you want to look up something specific and, if the example or tutorial requires you read a previous example or tutorial, it can lead to a lot of jumping around.  At the very least, provide links/page numbers for prerequisite examples/tutorials so you can more easily find them.

Also, it'd be nice if all documentation, manuals, guides, etc. were available in the same formats.  As an example, there is one application I use where one guide is built into the program, which requires switching back and forth between the documentation and project windows.  Annoying, as I've previously indicated, but I can work around it.  But then, another part of the documentation is online and others are PDF.  And they are all listed in the same menu and it's easy to forget which is which and nothing in the menu tells you which is which, so you click an item in the window and, unless you remember, you don't know if it's going to open in the program, in a web browser or as a PDF.  For the love of everything good, please don't do that.  Don't have scattered documentation.  Either put everything in one format or offer everything in multiple formats.  Don't mix and match and drive users batty.

[Grant Robertson]

10 minutes ago, dcr said:

I also like to be able to print PDF manuals...

Yup. These are all rules I adhere to was a matter of course, as a technical writer.

[ADRs]

+1 for this to, contrary to most of younger generation nowadays (especially my students), i like to read a PDF manual, whether it software or hardware.

[loukash]

+100 for a PDF manual.
That said though, a good PDF manual is hard work. A PDF without a properly linked TOC and clickable links ain't worth much either.

[Granddaddy]

Agree with all of the above. Books are best, whether on paper or on screen.

Short tutorials and help topics about tools are all well and good. Learning how to choose which tool to use when and for what purpose is a whole other story. You can give a man a Shopsmith along with instructions and tips on how to use a saw, chisel, planer, and lathe, but don't expect him to build a grandfather's clock.

I think some people made a lot of money writing and producing The Missing Manual Series of books. I bought one for Photoshop Elements a couple of decades ago and read it all the way through. I used to enjoy reading thousand-page software manuals in my working years. Books by O'Reilly come to mind.

That people no longer have such resources that put things together into a coherent whole explains a lot. 

Then again, there are many who choose to remain uninformed and feel it an imposition when you say they must understand how to do whatever it is that they are doing. 

[Grant Robertson]

2 hours ago, loukash said:

+100 for a PDF manual.
That said though, a good PDF manual is hard work. A PDF without a properly linked TOC and clickable links ain't worth much either.

Fortunately, almost every piece of software that generates .PDF output makes these easy to do. One simply has to bother to select the correct options.

 

Now, a good manual, in general, is actually very difficult to write and organize. As a skilled technical writer, I am dismayed to see that almost every software company, and almost every book publisher seems to have simply settled for what "looks like" a well-formatted document, rather that an actually well-written one. "Ink in the shape of a document," if you will.

[dcr]

Also, in addition to having a useful guide, said guide should also be proofread and tested.  It's pretty frustrating when you're trying to learn something and you follow the instructions step-by-step and it doesn't work.  And then you repeat and are more careful and it still doesn't work.  And then, if you're lucky, you find out it was due to a typo.  If you're unlucky, you give up and curse the day you bought the software.

So, companies should definitely proofread and test.  And the person doing the testing should be someone who has no idea how to use the software so they don't overlook errors because they already know what they're doing.

I recall throwing a guide across the room (the same book more than once) in frustration.  It was a programming book.  I had typed the example in exactly as it appeared in the book.  Didn't work.  Went through it line by line to double check and it still didn't work.  Went through it character by character, ensuring what I typed in was the same as in the book.  No luck.  Very frustrating.

I assume it had to be a typo or something missing that I wasn't yet knowledgeable enough to find on my own.  As I recall, I pretty much gave up on whatever it was I was trying to do.  And, there was no website forum back then to ask on.  Encountered a similar problem with another example in a different IDE years later and that was due to a typo, so I figure the earlier one was likely the same kind of situation.  If I remembered what it was, I could go back and check, though I don't know if I want to confirm that a typo in a programming guide threw me off learning programming for too long.  Geez.  Who knows if I could have made a killer app way back when but it never happened because of a typo in a learning guide?  Is there a statute of limitations for suing over errors and omissions in books that prevented you from learning how to program and, thus, missing out on countless opportunities?  I could be a millionaire by now if not for a possible typo someone else made.

At any rate, it's extremely frustrating trying to learn something only to fail not because you're stupid but because a semicolon or something is missing and you don't know enough to look for that sort of thing.  Granted, programming IDEs are more sensitive to typos than design programs but errors or omissions can still be frustrating, like if a design tutorial says to use a specific tool and that tool has been moved, renamed or otherwise not included in the version of the software you're using.  Or if it was in the development version but got dropped or moved before the released version but the documentation wasn't updated.

And then there's sometimes the part where they seem to skip a step.  And you follow step by step and it's like, um, something is missing here.  The tutorial shows a flower at this step but I've only got a circle.  Where did the petals come in?  How am I supposed to apply a gradient to the petals I haven't been shown how to make yet?

 

32 minutes ago, Granddaddy said:

Then again, there are many who choose to remain uninformed and feel it an imposition when you say they must understand how to do whatever it is that they are doing. 

True, but sometimes it can be difficult to learn what you need to know when you don't know what you don't know and there's no helpful guide to get you to understand what you don't know so that you can figure out what you don't know so you can research it and learn it.

[ADRs]

3 hours ago, Grant Robertson said:

Fortunately, almost every piece of software that generates .PDF output makes these easy to do. One simply has to bother to select the correct options.

And fortunately, Serif have Affinity Publisher, so the PDF should be good if the software itself is good.

 

3 hours ago, Grant Robertson said:

Now, a good manual, in general, is actually very difficult to write and organize. As a skilled technical writer, I am dismayed to see that almost every software company, and almost every book publisher seems to have simply settled for what "looks like" a well-formatted document, rather that an actually well-written one. "Ink in the shape of a document," if you will.

I agree with this, and by looking at the manual they published, i would know that if it is a really good "user manual", or only a developer "feature documentation".

sometimes i really hate it if i read some "user manual" that feel like it just a documentation that didn't help at all but labeled as user manual😞.

most of the open-source software i used have tendency to write like a developer documentation rather than aimed at user (and i can understand why). But if it is a paid product, a good user manual is a must IMO.

  

2 hours ago, dcr said:

True, but sometimes it can be difficult to learn what you need to know when you don't know what you don't know and there's no helpful guide to get you to understand what you don't know so that you can figure out what you don't know so you can research it and learn it.

I remember the first time i try learn about electronic music gear, it is a steep learning curve but fortunately most of the gear i bought/used have a beautiful, detailed and well-structured (printed) user manual that i can refer to anytime i need it, and only ask/find someone more knowledgeable (internet is still rare back in the day) whenever i don't know about something that i can't find the answer on the manual.

 

 

[benam]

+1 for all of this.

A PDF manual definitely makes things easier, and being able to put it in a binder makes it nice and easy to flip through the entire manual.
Please Serif! You already have HTML documentation, you already made workbooks for V1, can we see a PDF for V2 with everything in it?

[MikeTO]

 

[meyer.wil]

On 12/13/2022 at 9:35 PM, deeds said:

100% Agreed!

There's another (implicit) benefit of PDF Manuals... providing one forces the software maker to think about and articulate their product's features in a linear and complete manner. This, quite surely, benefits everyone; including the software maker, as it will more easily reveal workflow problems and excess user interactions for any and all operations.

It is a sad reality, too, that the non-linear composition of help files all but guarantees skimpy exposition and poor coverage. 

[Grant Robertson]

Thanks for providing this link in this thread. I have downloaded your book. Though, I haven't had time to read it yet. It looks pretty nice so far. 

[MikeTO]

On 9/19/2023 at 6:06 PM, meyer.wil said:

It is a sad reality, too, that the non-linear composition of help files all but guarantees skimpy exposition and poor coverage. 

When you write online help you have to keep it shorter for viewing inside the online help viewer, even if you provide a web version of it as Serif and Adobe do. Serif has also wisely chosen to bundle the online help with the applications rather than requiring internet access - Adobe requires internet access unless you choose to manually download the help files. But including them means you have to use very few screenshots to keep the total package small because screenshots must be localized to each of the eight languages that Serif supports and there aren't separate installers for each language.

Managing the online help for Affinity would be a difficult task because there are so many overlapping features in the three applications. if you make a change to character formatting, you have to change the help page for the three apps multiplied by eight languages for a total of 24 pages. And that's if it's only mentioned on one page. If it's mentioned on three pages then that would be 72 pages to update. It's so much easier to write a manual for a single app in a single language. I can add as many examples and screenshots as I like.

After spending more time in Publisher's help file than probably most users, the main recommendation I'd have for improvement is to eliminate the pages that aren't part of the primary navigation system. Some pages are in the left nav, others are not, so you're never really sure if you've read everything about a topic. The reason for these pages to be omitted from the navigation is so that they can be referred to from more than one place, but as you said it makes it non-linear. If everything was in the nav then you could read through the Publishing and Sharing section from start to finish and know that you'd read it all. This would be a big change so it's not something that could be done easily.

[meyer.wil]

On 9/24/2023 at 8:49 AM, MikeTO said:

Managing the online help for Affinity would be a difficult task because there are so many overlapping features in the three applications. if you make a change to character formatting, you have to change the help page for the three apps multiplied by eight languages for a total of 24 pages. And that's if it's only mentioned on one page. If it's mentioned on three pages then that would be 72 pages to update. It's so much easier to write a manual for a single app in a single language. I can add as many examples and screenshots as I like.

My comment was not specific to Serif, nor to Affinity help files, but to the challenges in assembling non-linear help files. A technical book is a major undertaking, but easier to manage than help files. Easier, at least, to assess coverage. There are good, common sense approaches to attempting to manage coverage in help, but those I have seen are simply disciplines, and depend on the use of separate tools, usually search tools, for their success.

I will continue to assert that the quality of documentation has deteriorated in the industry at large, since printed manuals ceased to be produced. Most help files are designed for reference use, not for learning. To that degree, Affinity help is better than many I have seen.