Go Back
2 Votes

pdf documentation for v11


Closed

Provide a PDF version of the Synergy V11 documentation.

6 Comments | Posted by Bill Ferris to Documentation on 5/6/2021 9:21 PM
Steve Ives
Hi Bill,

I can't help wondering whether you actually want a PDF version of the documentation, or whether what you are actually asking for is a locally installable copy? If that is the case then it already exists, you can download the installation from the resource center.

Unfortunately, if you really do want PDF files I would like to understand why, but I'm afraid it's not likely to happen. The feedback that we have received since the switch to web-based documentation has been overwhelmingly positive, predominantly because the new format is so much easier to navigate, search and use, including searching via web search engines. And most developers don't need a local install.

5/13/2021 5:03 PM   0  
Bill Ferris
Steve --  Yes, I actually want a PDF version of the documentation.  

5/13/2021 5:09 PM   0  
Bill Ferris
Steve --

Now that I have some more time I'll provide a more complete answer.

I'm not saying that a PDF version of the documentation is always (or even usually)  preferable to web based documentation.  But I am saying that when PDF documentation is abandoned in favor of web based documentation something is lost as well as gained.

Like most things in life it depends on context, circumstances and perspective.  I've only looked at the web based documentation briefly, but I don't see that there's a way of printing a complete manual.  (As I write this I can already hear the "that's so 1980s" comments.) 

With web based documentation you really only get to look at things in blocks and snippets. Frequently that's helpful.  If I want to know how a specific subroutine works, I really don't care about anything other than that subroutine.  Also, since web based documentation has more context I can see where it could also be tightly integrated into the development environment.   

But when you need to move between multiple topics, I find that web based documentation (in general) can sometimes be kind of clunky.  

Furthermore, if you want to fully understand how a product works (let's say Synergy .Net Development) it's sometimes beneficial (for me) to print the entire document, read it over the course of a few days, and mark it up with little notes and questions in the margins.  I would not do that with things like the Synergy Language Reference guide, but for something that includes set-up and high level concepts I often will.   That functionality is now gone, as far as I can tell.

So, my idea was not that the web based documentation should be abandoned, or that a PDF is always preferable to web based documentation.  It was that a PDF version should still be available, because there are circumstances where it is still preferable.

5/15/2021 4:03 PM   1  
Penelope Perkins
I understand what you're saying about it being easier to consume some types of information in PDF/printed format than in HTML. I'm the same way: I frequently print things out or make a PDF.
 
Although you can no longer print a whole chapter or manual from our web-based documentation, you can print individual topics to either a printer or PDF. For best formatting results, use the print button in the toolbar at the top of the topic rather than your browser's print function. In the print dialog, you can adjust the margins if you'd like to create a wider margin for note-taking.
 
When Synergex made the move to web-based documentation several years ago, the documentation team changed its tools and processes accordingly. This means we no longer have the capability to produce PDF manuals as we used to. I hope the workaround I describe above will help meet your needs.

5/19/2021 12:08 AM   0  
Jack Ford
I know this is "settled law", but I have to echo Bill Ferris' eloquently and accurately stated position.  It's not that web-based doc doesn't have it's obvious virtues and advantages in many scenarios and usages, but an organized, top-down structured document that a PDF rendering provides has it's own very valid benefits, and at times, yes, advantages.  Without repeating his entire position that I identify with greatly, his comment about something lost as well as gained hits the nail on the head.  At my own risk of initiating groans and eye-rolls, I liken this to my practice of still using a command line environment alongside a GUI/mouse for THOSE CASES when it is still more efficient and quicker to get certain things done.  Completely eliminating one in favor of another is less than the sum of the two parts.

7/23/2021 4:43 PM   1  
Gordon Ireland
It is 1000% times better than trying to get answers from StackTrace, where the uninformed and the incomprehensible have various attempts to answer a question you didn't ask, with code snippets that don't work.   Seriously though, I find the online docs ideal, and you have the videos to give a good grounding in something new

7/29/2021 10:04 PM   0  
Please log in to comment on this idea.