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.
The new documentation home page offers immediate 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 single 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 which 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. Access the zip files and additional instructions for help.
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.
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).
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 improvements can be made.
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.
We sincerely hope the new documentation serves you well. Remember, we also have an excellent support team ready to help.
If you happened to be reading this but don't use Altium yet, be sure to check out your own free trial to find out for yourself why Altium is the best professional PCB Design software.
We are happy to hear your thoughts and feedback. Comment and share below.
About the Author
Phil is a member of the technical writing team, creating content that helps designers craft their next great idea in Altium's design software. Phil has been a part of the Protel / Altium team since the mid-nineties, working in technical support, training, product management and technical writing. He has a degree in Electrical Engineering from the University of Technology, Sydney, and a Diploma of Education from the University of Tasmania.
More Content by Phil Loughhead