Part of the Altium Designer 17.0 launch was a revamp of our documentation, making it much easier to find, and use up-to-date information. This document describes what has been updated and how to use the documentation resource platform.
Creating learning and reference resources for design software like Altium Designer presents an interesting challenge. On the one hand the software has a single overriding function - it’s a professional PCB design tool used to help a designer create and implement a printed circuit board.
But on the other hand, achieving that requires the designer to work in a number of completely different design spaces, or editors, all the while managing a large amount of data and design files.
As the designer, you have to draft the various representations of the components, capture that next great idea as a circuit, design the oddly shaped, folding board to implement the circuit, then generate the multitude of outputs needed to feed into the next stage of the process - fabrication, test and assembly.
So just how do you build a learning and reference resource to help a designer achieve that?
Documenting Altium Designer is perhaps more challenging than documenting the entire Microsoft Office suite! It’s similar in that it’s big and has multiple editors, so there’s a lot to say. But it has a bonus challenge - in Altium Designer it’s a single design process, so much of the knowledge content has to mesh with other content to tell the overall story!
And who is the audience? One of the pet peeves of everyone who seeks an answer to their question about software is, why are there so many words, why doesn’t it just tell me what I’m trying to learn? Every good story is written with the audience in mind, so just who is the audience for this documentation?
For software, the target audience is someone who is new to that thing / task / process, which means the documentation has to include more detail than an experienced designer might prefer. Keep that in mind if you start to feel frustrated after having to read 800 words to find the answer to that specific question about targeting the Vias that need to be back drilled...
Building a new documentation system from the ground up requires that the objectives are clearly understood. These objectives include:
So just how do you avoid creating a content dinosaur? Every so often, you stand back and ask, “is this working?”. Well we’ve done that, and the answer was no. The content was simply too old, had too much missing, there were too many mistakes, it was too hard to find anything, and would take too much work to fix! It was old content that had started life being paper/pdf-based, which had not traveled well as it first moved to a wiki, then on to a new content management system.
It was time for a fresh start.
What was needed was a new home for documentation - www.altium.com/documentation is that home.
For the Altium Designer documentation, every one of the 2500+ reference pages was reviewed and rewritten, adding detail and depth. These reference pages document every: command, object, dialog, panel, wizard, design rule, preference, compiler violation, and query language keyword. Press F1 over any of these in the software and you’ll be presented with a page of reference information.
For the higher-level learning content a simpler structure was defined, totaling some 200+ pages. Every one of these started as a blank page, its page structure defined, the topic researched, and content written.
An overriding objective for the new documentation is to connect relevant content. For example, the Multi-Sheet and Multi-Channel Design article includes over 30 links to other pages: to pages about related design tasks such as creating connectivity and cross probing; to the various design objects that are mentioned; and to relevant panel, dialog and preference pages.
Another objective of the content re-structure process was to present the high-level content in a design-centric way, instead of the old software-centric structure. For example, you’ll now find the information on working with a Vault component right next to the information on working with database components, or building a schematic symbol. In fact, for Altium Designer 17.0 and on, all of the content about using a Vault is now part of the Altium Designer documentation, with the Vault installation, configuration and management information living in a separate documentation space, accessed via the documentation home page.
There’s nothing worse than finally finding the explanation you were after, only to find that it is not up to date, with no information about that new option you’re wanting to use.
This problem has been solved with the introduction of versioning. The new Altium Designer documentation starts from a base version of Altium Designer 15.1. You can manually switch to a particular version of the documentation, using the drop down selector at the top of the navigation tree. And from Altium Designer 17.0 onwards, if you’ve opened the documentation by pressing F1 over the software, then you’ll automatically be taken to the correct page for your version of Altium Designer.
For those using Altium Designer 17.0 or later, pressing F1 already connects you directly to the rich, new documentation at altium.com/documentation.
For those using Altium Designer 15.1, 16.0, or 16.1, the required F1 mapping 'smarts' are not inherently present in the software. But that doesn't mean that you need miss out on the party!
We've prepared zip files containing variants of the F1 mapping file found in Altium Designer 17.0 - ADES.HelpID - connecting each of these earlier versions to their corresponding documentation at altium.com/documentation:
Simply download the applicable zip file and add the extracted files to your installation, as detailed below:
Now you can enjoy access to the new documentation world directly, with full documentation coverage for the software's extensive resources.
Gone are the days where every designer sits in front of a desktop computer with a single, 1280x1024 monitor. Today our desktop PCs have multiple monitors, of various sizes and resolutions. We also need to be able to work from our laptop when we’re in the field, or at the client’s office. And since we’re knowledge geeks, we also like to be able to use our tablet or phone to soak up more information while we’re waiting for that flight, or catching the bus to the office.
So how do you present the content so that it works on all of these different devices? The right way to solve this conundrum is to use what is referred to as responsive web design. A responsive website communicates with the target device, adjusting the layout and size of the content to suit that device, screen resolution, and browser size. You can get a taste of this by resizing your browser, as you shrink the width the page elements rearrange, and the fonts and images get smaller. Even on a 5 inch screen the site is functional, for example the navigation tree is still available on your tablet or phone, as a dropdown.
So you’ve opened the site, and have the 2700+ pages worth of content available to you. Now you face the challenge that comes with all online content - how do you find what you want, without it becoming a hair-pulling experience!
There are three ways into the content, you can: press F1 over the command / panel / dialog / object in the software; or you can browse; or you can search.
The site includes a navigation tree on the left, use this to browse through the site content. Most pages contain information, some are there simply to create the structure of the site, when you click on one of these the lower-level tree will expand. If you want more screen area, use the control to collapse the pane.
In the navigation tree you’ll find the high-level content towards the top, with the reference content below it. The detailed content that explains how to design in Altium Designer, that’s in the Exploring Altium Designer section.
Within a page you can browse using the page-level Contents pane that presents at the top of most high-level pages. The Contents pane automatically collapses to the top of the page as you scroll too, so it’s always available, regardless of where on the page you are currently reading. When it’s collapsed, it also displays the name of the section you’re currently reading.
Many people prefer to search to find what they’re after. The site search has been greatly improved, you access it via the magnifying glass icon on the left of the page.
Documentation only has value if it helps you, the reader. For the writers to know that, they need to be able to get feedback directly from the reader. With over a million words spread over 2700+ pages, the reader needs a simple and immediate mechanism for sending their thoughts.
To support that, the site has a new feedback mechanism that can be run from any page. Simply press Ctrl+Enter on the keyboard to open the Send Feedback dialog. If there is a particular section of text you’d like to reference, select it before pressing Ctrl+Enter (up to 200 characters).
When you click the Send Feedback button, an email is sent directly to the writing team. If it’s an unusual request or a tricky topic to understand, a team member will use your email address to contact you for clarification. Your feedback is genuinely appreciated, we know you’re giving up some of your precious design time to explain a problem with the documentation.
In case you’re wondering why some of the pages have an 'under construction' banner, or that specialized design topic you’re looking for is not covered, don’t worry. What you see today is just the beginning - the foundations of a new documentation system. The writing team are busy chipping away at the outstanding content, and have some ideas on how to improve the site in the future.
The new world supports versions, so all of the existing content will continue to be available. Support for versions also solves a difficult challenge the writers have always faced, being able to update existing content in readiness for the release of a new version of Altium Designer. Now a new version page can be prepared off-line, ready for release along with the software.
The content is now authored in an online content management system, creating the opportunity for others in the broader Altium team to contribute. The system also supports alternate languages, alternate language versions will be released as they are ready.
Being an extensible, web-based authoring/publishing system, it opens the door to explore new ideas that improve the functionality and usability of the site and its content. Two such ideas that the writers are planning to raise, include:
The forum is a rich resource, full of real-world challenging questions, and creative and detailed answers. It would be fantastic to be able to mesh content from the forum into the documentation, as a new Q&A page.
This could be done by manual harvesting - where a forum post with a great question get tagged as a question, and the best response post(s) gets tagged as the answer(s). Or perhaps it could be configured as an automatic user-voted Q&A system, along the lines of the StackExchange sites.
Back in the new documentation site, the Q&A page would automatically monitor and locate suitably tagged posts, and presents the tagged question + answer(s).
Configurable Search - the idea is to add a scope drop-down next to the search box, where you can restrict the search to the: Site, Space (e.g. Altium Designer documentation), Branch (from this page down), or Page (so you can perform a true all-word page search, rather than relying on the browser’s page-level literal string search feature).
The writing team are enjoying working in the new, versioned documentation system, and are excited by the possibilities it offers into the future. The new feedback system means that simple mistakes can be fixed immediately, and will also help us develop a deeper understanding of where content is failing to deliver, and can be improved.
The writers are backed up by a talented and responsive web development team who have breathed life into this new documentation authoring and delivery system - they are deeply appreciated for making all of this possible.
Complete this form to request a free 15 day trial of Altium Designer: