A New Era for Documentation

Modified by Jason Howie on Jun 1, 2017

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.

Altium Designer Documentation: The Challenge

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...

The Objectives

Building a new documentation system from the ground up requires that the objectives are clearly understood. These objectives include:

  • Keep it relevant - old documentation is a bit like old news. Tacking new words onto an old story takes away from that story, making it harder to understand, and more frustrating to find the meaning of that critical piece of information. The writer must always be willing to re-tell the story as the software evolves and the reader’s design schemata expands.
  • Keep it accessible - the software is the star, the words and pictures are there to help the designer work in that software. The less the designer has to lose their focus to achieve that, the better. That means they need to be able to find that answer quickly, through F1, cross-links, browsing or searching.
  • Keep it current - there’s nothing more frustrating than looking in the instruction book, only to find that it describes a different model widget from the one you’ve just unpacked. This can only be solved by having a version of the documentation for each version of the software.
  • Keep it growing - design software grows and changes to meet the changing needs of the design challenge - what was once a bunch of small copper pipes carrying current across and through a board, are now a set of transmission lines that need their paths and the materials they travel through to be carefully designed and managed. Like the software, the documentation has to keep pace with the designers’ needs.
  • Keep it meaningful - perhaps the greatest and most important challenge of all is knowing that the words and pictures tell the story in a way that works for the reader - so they can have that lightbulb moment and quickly return their focus to their design. Like well designed electronics, a feedback system is essential for this to be possible.

The Solution

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.

The Content

What was needed was a new home for documentation - www.altium.com/documentation is that home.

The new documentation home page gives access to the various documentation spaces.

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.

The Right Content

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.

Use the selector to explore the features in a different version.

Updating F1 for Altium Designer 15.1, 16.0 & 16.1

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:

  • ADES_15_1.zip - containg ADES_15_1.HelpID and ServerDlls.txt files, mapping Altium Designer 15.1 to the version 15.1 documentation for Altium Designer.
  • ADES_16_0.zip - containg ADES_16_0.HelpID and ServerDlls.txt files, mapping Altium Designer 16.0 to the version 16.0 documentation for Altium Designer.
  • ADES_16_1.zip - containg ADES_16_1.HelpID and ServerDlls.txt files, mapping Altium Designer 16.1 to the version 16.1 documentation for Altium Designer.

Simply download the applicable zip file and add the extracted files to your installation, as detailed below:

  1. Close any running instance(s) of Altium Designer.
  2. Drop the ADES_xx_y.HelpID and ServerDlls.txt files into the \Help folder of your Altium Designer installation, allowing the new ServerDlls.txt file to replace the existing one.
  3. Remove the older existing HelpID files from the \Help folder. These are: ADOH.HelpID, AltiumDesigner.HelpID, and DMAN.HelpID.
This is an important step. The software collates the content of all HelpID files detected in the \Help folder, arriving at a single listing with which to interrogate for a match to an F1 call. Leaving these older files can lead to undesirable results, and likely send you back to the older documentation world (techdocs.altium.com).
  1. Restart Altium Designer.

Now you can enjoy access to the new documentation world directly, with full documentation coverage for the software's extensive resources.

Delivering the Content to every Device

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.

Using responsive design, the documentation can be accessed on all types of devices.

Finding the Answer

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.

Browsing

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.

Use the Navigation pane to explore the content, click the  control to collapse the pane if you want more screen area.

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.

Use the Contents pane to browse the topics on that page.

Searching

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.

The improved search engine displays the results in a new page.

The easiest way into the new documentation is to press F1 in Altium Designer.

Closing the Loop

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.

Please restrict your feedback to documentation issues - for technical assistance refer to the Altium Forums.

It’s easy to send feedback directly to the writers.

Foundation for the Future

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.

Preparing New Content

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.

Alternate Languages

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.

An Extensible System

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:

Forum-sourced Q&A page

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 Scope

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).

Content that Gets Better and Better

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.

 

English
If you'd like to comment on the content on this page, use the Ctrl+Enter keyboard shortcut to send us your feedback. To include a section of the page in your comment (a typo, missing/wrong info, or incorrect imagery), highlight the text (max. 200 chars) and/or image first. Please restrict your feedback to documentation issues - for technical assistance refer to the Altium Forums.

联系我们

联系原厂或当地办公室

You are reporting an issue with the following selected text and/or image within the active document:
Request Free Trial

Complete this form to request a free 15 day trial of Altium Designer: