Announcements: Techdocs - a new era for Altium’s technical documentation

This represents a significant milestone for Altium and kicks off the start of a campaign to ultimately get our documentation ‘house’ in order - and then some! It reflects our strong commitment to a singular overriding quest, and that is to provide high-quality, highly-relevant and accessible documentation to assist our customers to optimize their use of our design solutions.

As a humble, and battle-hardened author of many of Altium’s technical documents over the years, I feel empowered by the possibilities that this new documentation platform promises. Not only for myself and my fellow authors but, more importantly, what it can deliver for you as our readers.

So join me as I take you through what can only be regarded as the beginning of a new era for Altium’s technical documentation. Through this blog I hope to explain what it is about this new site and direction that has us excited, and along the way I’ll provide you with a little insider’s insight as to where we are, and where we are headed.

Not a ‘Wiki’

Before you roll your eyes and run for the hills, I can’t stress this point enough. I know how the very name ‘Wiki’ has drawn exasperated gasps of frustration from our readership over the years. Imagine my reaction when I left the office at 11pm one day producing PDF-based documentation, and the next day the Wiki was the ‘new world’!

A Wiki, by definition, is the culmination of efforts across a many and varied base of contributors, about a neverending variety of topics. Altium’s documentation, on the other hand, is a finite set of topics that, if we’re being realistic, can, and should, be written and delivered by members of the Altium Team. It is an unrealistic expectation to place that burden on our users.

With that, albeit late realization clearly in mind, the paradigm for documentation became one of delivering a premium content-managed system, rather than a documentation space driven by the Altium user community.

And we already had the platform to do this in place, having relaunched the Altium website earlier, and built on the open-source Drupal Content Management System.

Unified Delivery of Documentation

In the past, a barrier to getting documentation has been, well, ‘getting at’ that documentation. This was hampered by the silo’d approach to the documentation, with some Wiki articles here, some PDFs there, and some older-style WinHelp and HTML Help files thrown in to confuse the mix. Our divergent documentation completely flew in the face of our unified design software!

The techdocs site provides a single, cohesive environment from which to source all of the documentation - from the highest-level conceptual document regarding some new-release feature, to the lowest-level resource document explaining what a dialog control does, or how a command is used.

What’s more, by utilising the Drupal platform, we have been able to fully integrate the documentation with the AltiumLive community. As a general reader, there is no signing in required. But as a contributor, this means you no longer have to juggle a separate login. Simply sign-in once to AltiumLive with your usual credentials.

The First Step...

Having started with the company back in the days of 99 SE, I still have recollection of the size of the documentation available back then. A mere drop in what was to become a veritable ocean of words! Quite a double-edged sword in reality - the more that is written, the more that has to be maintained. And we were under no illusion as to the gargantuan task that lay before us.

But every journey starts with that first step. And I can proudly attest to the determination and rejuvenated outlook the merry band of authors have brought to the task. Concentrating primarily on resource reference material for the core technologies - namely in the Schematic and PCB area - I can share the following statistics of just what has been addressed in this initial site launch:

• 394 dialogs.
• 1541 commands
• 52 preferences pages
• 57 objects
• 13 panels
• 28 design rules

Not to mention a variety of ‘hot-off-the-press’ articles detailing the many new features available in the latest AD release!

Browser-based Dialog Help

Yes you read that correctly! We’ve steered the documentation away from reliance on out-dated help methodologies and technologies, favoring delivery of all documentation through the single, cohesive Techdocs site. In terms of dialog-level help, no longer do you need to click, click, and click again to see help for options in a piecemeal fashion. Now, simply press F1 with the dialog open and get a page of information on that dialog in its entirety – being able to see, at-a-glance, what each option and control does. Presenting information for a dialog on a browser page delivers numerous benefits, above and beyond that of its previous WinHelp-based incarnation, including:

• Ability to elaborate on the detail of a control, with additional note, information and tip highlight boxes.
• Ability to keep the information visible while clicking elsewhere in the dialog.
• Ability to add cross-linking to other pertinent areas within not only the technical documentation, but the wider AltiumLive community.
• Ability to maintain the documentation for a dialog in a far more streamlined and expedited manner – making updates without having to compile installable files.

This initial release sees a myriad of resources supported by this reinvigorated approach to F1 help functionality in Altium . And while you will undoubtedly run into resources that don’t pop a specific page, rest assured coverage will continue to grow!

Ease of Browsing

While accessing the resource material directly from the software is one means of entry, it is by no means the only method. For those who like to browse through the documentation using a nav tree and search facility, we have you covered.

For a start, you will notice that content has been separated into specific and specialized content areas. This practical grouping of pages offers a more logical browsing experience and facilitates quickly finding the information you need.

And the platform’s search facility also benefits from this partitioned approach, allowing you to either pinpoint documentation from across all spaces, or only that residing in the space at hand.

The Road Ahead

On any journey, it is difficult to know how long each stage of that journey will take, what obstacles may lay on the path, or indeed what might be encountered around the next corner. But armed with a fresh and powerful content management platform, dedicated support from developers who are Drupal Masters, and a growing team of documentation authors, we have already started to formulate a decisive plan of attack, in a campaign that will realistically span a number of releases to the software. The following are just some highlights of forthcoming attractions to whet your appetite (in no particular order, of course).

Offline Documentation

By using an open-source platform for our technical documentation, we are well placed to deploy localized documentation repositories without the burden of paying licensing fees for each deployed instance. In essence, it will provide you with the option of having offline documentation that doesn't require an internet connection. And with the ability to reconnect to the techdocs ‘mother ship’, in order to synchronize your offline repository with the AltiumLive-based ‘master’.

Content Quality

While this initial release has addressed a sizeable portion of the resource reference material, it is just the tip of the proverbial iceberg. A large part of this will be to address the higher-level content in the Altium space of the site. This features some 700+ pages of material which, in some cases, has exceeded its useful shelf life!

Getting this updated at the same time as providing additional new feature content is paramount and will go a long way to earning back some credibility with you, our users.

Reference Material

Having delivered an impressive array of resource material in this initial launch, we will of course be carrying that momentum forward. Addressing the remainder of resources for the core technologies, followed by the servers related to ancillary technologies thereafter. And let’s not forget the plethora of detailed references in need of an overhaul too!

Advanced Semantic Search

While the documentation can be searched, the current search is, at the end of the day, very basic in its nature. To bring credible results to our users, we need to take this basic search and turbo-charge it. To use tagging and indexing to empower the search facility, allowing advanced searching not just of the technical documents themselves, but of all other services within the AltiumLive community, and the wider Altium website as a whole.

Productivity Boosters

By introducing features such as annotation and sharing, you will be able to create your ideal documentation ‘set’ and share it among your team. Just think of the ability to mark a page of the documentation with some well-honed personal remarks, and then share those with others - clip notes on a whole new level!

Language Support

Many people have asked me over the years why support for different languages has never appeared to ‘take off’. And this is a very good question. Various spaces for a range of different languages have been available, but their content has never really mimicked that of the English content space. But again, that has more to do with the authoring tool available than the dedication of the authors in those spaces. But now, with Drupal as our platform, we have the ability to re-energize this whole area.

For us, supporting multiple languages across our technical documentation is an important part of our global operational reach, and one which we very much intend to deliver upon moving forward.

Bear with Us

I hope that this blog has, in some real way, helped to allay any fears that you may have had in regards to our focus and intentions to effectively turn our documentation around, and deliver a complete set of technical documentation that both you, and we, can be proud of. Documentation worthy of sitting in support of the esteemed software for which it is being written.

So while there is still a long road ahead of us – both in terms of documenting the resources, and the wider documentation set in general – all I can say is bear with us. This is just the first step towards full and accurate coverage of the software's features and functionality. A goal that we all can agree is long overdue, but one that we are confident in realizing!

For the latest Altium documentation, click here.