Summary: With the Build-a-Book feature in the TechNet Library and MSDN, you can combine topics into a package to download for offline reading or printing.
Microsoft Scripting Guy, Ed Wilson, is here. Today’s post is by Dave Bishop. He explains a cool new tool that enables readers to print documents directly from content in the Microsoft TechNet Library and MSDN.
Dave is the manager of the Windows Server Manageability Documentation team at Microsoft, which includes the documentation for Windows PowerShell. He’s a former ITPro, and a long time scripter who has automated many of his daily tasks with Windows PowerShell.
Take it away, Dave…
At Microsoft, we have been publishing documents to the web for a long time. The team that I lead (Windows Server Manageability Documentation) and my peer teams used to be in the business of writing chapters for books and producing a lot of Help files that were included “on-the-box” with the Windows and Windows Server operating systems. These days we produce very few of either for many reasons. The biggest reason is a shift to publishing our content on the web, which enables us to keep it up-to-date. Books and Help files had to be finished months before the products they described were released. This almost guaranteed that they were out-of-date as soon as they were published. When updates and Service Packs came along, that static content quickly became more inaccurate, and we frustratingly had (and still have) almost no opportunity to update that content.
On the other hand, content that we publish to the Microsoft TechNet Library on the web can be updated quickly and regularly, enabling us to fix mistakes that slipped by, add more information where a gap was identified, and so on. We think that is a huge win for our customers and we’ve gone all-in to move our content to the web. Because of the ability to update our content, it also means that feedback from our customers is more important than ever before! Although we always were interested in feedback, we can now do more about it, so please continue to rate topics and provide your comments.
All that said, the switch to web-based content was not without some perceived drawbacks. Some of you made the adjustment from paper books to the browser well, but others still prefer to capture some reading material in a form that can be reviewed offline. Until recently, that meant that we had to package our more popular documents as Word or PDF files and post them to the Microsoft Download Center where customers could download and print them. Although we certainly understand the need for that, it meant that we had two documents to maintain instead of only one, and we risked accidentally updating only one of them. Obviously, that’s not a good experience for anyone!
Recently, the folks who maintain the infrastructure for TechNet and MSDN introduced a new feature that the writing teams are very happy to see. We call it Build-a-Book, and it enables you to combine any topics that you like into a single package that you can download for offline reading or printing. Let me introduce you to this very cool feature…
Imagine the following scenario—and you can follow along if you’d like; the feature is live today!
You are a new convert to Windows PowerShell because of The Scripting Guy’s excellent blog and the recently completed Scripting Games. You want to learn more about this truly awesome technology, and your search brings you to the following Windows PowerShell site in the TechNet Library: http://aka.ms/kdehpr.
After browsing a bit, you decide that you want to download the entire Getting Started with Windows PowerShell document—maybe even print it. In the “old days”, the only way to print from the TechNet Library was to navigate to each page one-by-one and then print from your browser, usually resulting in lots of wasted paper because so much of the Table of Contents and the page’s “chrome” was included in the printout. Yuck. Super tedious. So 20th century.
Instead, let’s try the new improved process. In the upper-right hand corner of the page, click the Print icon, and then on the menu that appears, click Print Multiple Topics.
This takes you to a page that explains the downloading process and how to select topics to include. By all means, read it; but I won’t bother repeating it here. Click the Start button on the left side of the page near the top. You’ll find yourself right back at the TechNet Library page from which you began this little journey. But now your vehicle has a new dashboard accessory in the form of this little toolbar:
The presence of this toolbar shows that you have the Build-A-Book feature turned on, and it’s ready for you to start assembling your package. Notice that you can easily add the topic you’re currently viewing—simply click Add this Topic adjacent to the green plus sign. But in our scenario, we want to add the entire Getting Started with Windows PowerShell document. That’s easy too. All you have to do is to right-click the title of the topic that is the parent of all the topics that you want to include, as shown here:
To make sure, the system asks you if you want only the one topic or all the topics included in that branch of the tree—in this case 45 topics. Click Add This Set of Topics (45), and you’ll see that the toolbar updates to show that your collection is 45 topics heavier.
To make the rest of this example a bit more interesting, let’s also grab the Windows PowerShell User’s Guide. Right-click that topic in the Table of Contents, and then click Add This Set of Topics (43). Now your collection has 88 topics.
Let’s examine the collection. Simply click the Collection link in the toolbar, and the following page appears:
You can see that your collection is named My Collection; and currently, it contains a single chapter creatively named “Chapter 1”. That chapter contains the two sets of topics you selected. Before downloading it, let’s tidy things up a bit. First of all, click Rename next to the My Collection name, type a new name with a little more context and pizazz, and then click Done. In my example, I used Starting the PowerShell Journey. Isn’t that so much catchier than My Collection?
Next, let’s turn each document into it’s own chapter. Click Add Chapter in the upper-right:
Give your chapter a new name by typing “User’s Guide”, and then click OK.
Now you can drag the Windows PowerShell User’s Guide document down to your new chapter. Left-click the four-arrow icon that is located on the left of the document, then drag it from its starting location to where you want it. In this case, drag it to directly under the User’s Guide title.
All that’s left to do is to rename the original Chapter 1. Click Rename there, and type “Getting Started Guide”. When you’re done, it should look like this:
Before we actually download the collection, let’s check a few other options. Click Advanced Options to see the (ahem) advanced options.
- Example Code Language lets you filter to include only the examples that use the language(s) that you are interested in. When an MSDN topic supports many different programming language examples, this option can be very useful. (We’re working to get Windows PowerShell added to this list!)
- Include Community Content lets you choose whether to include content that was written by people outside of Microsoft. Sometimes there is some truly excellent stuff out there, so be sure to review it before making a decision here.
- The final option enables you to specify how to handle translated content. Do you want to include the original (likely English), the translated version, or both?
Finally, you can specify how you want to download your newly customized book of knowledge. For this example, select PDF from the drop-down list, and then click Generate. If you are not yet logged in, you’ll be asked to do so before you can download your completed file. Give it a few minutes. Depending on how many topics you included, the server takes a bit of time to process and add them to the downloaded file. As long as the Current Topic: title changes every few seconds, it’s on track.
When it displays the following page, right-click Download Your Document, click Save target as…, and then specify the file name and folder where you want to save your finished document.
After it’s saved locally, you can use your favorite PDF reader program to view it, transfer it to your favorite eReader device (most of them support PDF files), or print it for that truly classic “paper” feel. Your collections will persist for the session, so you can go back to add additional topics, remove topics that you don’t want, or totally rearrange the whole document. It’s completely up to you!
I hope you think this new feature in the TechNet Library and MSDN is as cool as I do. It simplifies our publishing to one location and gives you additional flexibility to download and print topics or collections of topics that are useful to you.
Please let us know what we can do to improve your documenation experience. You can email me and my team at mgmtdocfb@microsoft.com.
~Dave
I invite you to follow me on Twitter and Facebook. If you have any questions, send email to me at scripter@microsoft.com, or post your questions on the Official Scripting Guys Forum. See you tomorrow. Until then, peace.
Ed Wilson, Microsoft Scripting Guy