What’s New with the Wolfram Documentation Center
March 30, 2020 — Brian Van Vertloo, Document Technology Manager, Document & Media Systems
The Wolfram Language is the culmination of decades of effort, supporting all our products. One reason the Wolfram Language is so easy to use is the Wolfram Language & System Documentation Center—unique in that it contains reference information along with tens of thousands of examples that can be edited and run in place (or quickly copied from the web to your notebook).
We recently released Version 12.1 of the Wolfram Language, and with it, a number of new documentation features and page types. With every release, you’ll find an increasing scope of functionality, examples and use cases documented for different fields and applications, presented with an intuitive, user-friendly design.
The Home Page
The Documentation Center’s home page is organized by topic and demonstrates the vast coverage of our knowledge-based language. There are three stacks of tiles for different needs: Wolfram Language reference material; task-oriented, step-by-step documents called workflows; and additional language resources.
New Features in the Language
Before we dig into these tiles in depth, let’s first see how to find what’s new in the latest Wolfram Language release. There are two notable ways to do this from the home page: the Recent Features tile and the New Features footer link.
The Recent Features tile takes you to the Recently Added Features guide page, which outlines handy resources for each of the recent Wolfram Language releases. This landing page contains links to announcement webpages, new function listings and revision history:
This page includes a link to the Summary of New Features guide page for each release—also linked to from the bottom of the Documentation Center home page. This summary page is a great way to discover new and updated functionality. Some of the new features in Version 12.1 include computation with video, substantial advances within machine learning, major updates to geographic visualization and more.
Finding What You Need
The backbone of the Wolfram Language documentation is the guide pages. Each guide page is a topical, loosely hierarchical page that contains links to functions relevant to that topic, roughly in order of importance to that topic. On one hand, a guide page is a table of contents—a quick reference to functions on a topic—but it’s also a node in the network of Wolfram Language documentation, with the colorful tiles on the home page serving as the primary entry point. You’ll find higher-level guide pages linked directly from the home page, and each of those guides typically contains many links to other, more specific guides.
Across all pages, especially those documenting specific functions, we ensure that users have a seamless experience in finding what they need. This includes the addition of visual differentiators, established assets and some other noteworthy UX choices when it comes to interlinking various networks of functionality.
Quick Access to Related Content
Thoughtful, curated linking of related content is a principle carried into every area of our documentation. Function-specific reference pages have dedicated areas at the top and bottom of the page with links to related pages. You’ll see some combination of these drop-downs at the top of any reference page:
In the following screenshot, you’ll notice the gray bar spanning the top of the page. This is the sticky header on our web documentation. It appears when you’ve scrolled away from the top of the page, providing you with the top-of-page drop-downs in case it’s time to jump to related content.
Each of these link sections has a stylized icon (at the bottom of the page on the left-hand-side) for quick visual reference. Similarly, Related Links have Wolfram product icons when applicable:
A common complaint in previous versions was that closed sections were often hard to see when browsing a page. Now, these closed sections often include an image preview of the hidden content:
These previews are generated by capturing the section’s content in an image, splitting it vertically and placing the resulting list of images in a row—all produced by the Wolfram Language.
You may have noticed that guide pages have dedicated link colors for certain types of reference pages. You can now determine at a glance whether you’re looking at a built-in or package function, an entity type or another reference page type. System symbol links are blue and non-symbol reference pages are quoted and light gray:
Entity page links have their own style too; they’re similar to entity pods and light up when hovered over or clicked:
Other link styles include package symbols (light blue) and non-Wolfram Language functions, such as WSTP C language functions (green):
A workflow takes a different approach from the categorical reference material. Workflows are task-oriented pieces of documentation, providing a step-by-step walkthrough of that task. Workflows are also used to show tasks involving interface items or other user actions outside of the literal syntax of the language, such as external program setup, and includes screenshots or diagrams to accurately describe those processes.
While workflows are intended to be standalone documents, they are grouped together by general topic in, as you may have guessed, workflow guides. For example, the top-level workflow guide Working in the Cloud contains a number of links to workflows (and workflow guides) on interacting with the Wolfram Cloud.
Resources for the Wolfram Language
Within each tile opener on the home page, you’ll see links to related categories within Wolfram repositories:
Near the bottom, there is a third group of links under a Resources heading for related out-of-system documentation and general information regarding the use of Wolfram products.
Usability Features on the Web
Responsive and Mobile Friendly
Our web documentation pages are all fully responsive. This means that no matter what device you’re using, you get the same webpage, but the font sizes, white space and various page data will adjust accordingly based on your browser window size. Here’s an example of how that happens horizontally:
Unique to our documentation is that we also respond to vertical breakpoints in the same way:
If you’re viewing web documentation narrowly on the side of your notebook window, shortened above or beneath a notebook, or on a separate screen entirely—our webpage responsiveness has got you covered.
Previews on Hover
We have two new web features for previewing content before clicking through the site: guide previews on the home page and function template previews from guide pages.
From the home page, hovering over a guide link will pop up a preview of the guide itself. This preview is fully interactive, including relevant hyperlinked functions that users can click to jump directly to the reference page and skip the intermediary guide:
While on a guide page, hovering over the link to any reference page with a top-of-page template box will give a preview of documented function patterns:
For web documentation users who only need a refresher on the syntax of the Wolfram Language, this second feature will be all they need. It’s comparable to the function template tooltip (an in-notebook feature and part of the Wolfram Predictive Interface).
Copy to Clipboard
When viewing a reference page on the web, you can select any example’s input to immediately copy its contents to your system clipboard:
In the same hover effect, there’s an icon providing an anchor link to that example (for later reference or ease of sharing):
Easily copying examples from the web is more useful than you might initially suspect. Not only does it save the time otherwise spent rewriting the example in your notebook, but it is also helpful when copying an example that contains something that isn’t text. For example, the first basic example for the function ImageResize looks like this:
This example copies as faithfully as any other; pasting in a notebook shows the image inline, just as you see it on the web.
Another useful feature is the ability to copy an entire usage template, which then pastes (with placeholders) into a notebook:
Copying templates like this is an online analog of the function and option templates from the Wolfram Predictive Interface tooltip.
Easily copying content from the web to your notebook is especially powerful in the Wolfram Cloud—where you can now quickly evaluate or tweak documentation examples just as in the desktop product.
More of What’s New
A good search system can be crucial for finding the content you need. That’s why considerable optimizations and improvements have been made to searching our documentation, both within the product itself and on the web. These improvements are architected in-house using our own search technology.
The search results page itself is slightly different in the product versus on the web, but either way the focus is on visual cues for finding the content or page type desired.
New Page Types
Often, new functionality needs to be documented in specific ways, and we craft entirely new kinds of reference pages to accommodate that. Although there may be significant differences among these new page types, the overall design principles are still apparent. Here are some of the new page types introduced in recent releases:
Here’s a list with examples:
- Entity types (AdministrativeDivision)
- Compiled types (Integer8)
- Data structures (DynamicArray)
- Database connections (MySQL)
- External evaluation systems (Python)
- Classifiers (CountryFlag)
- Predictors (NameAge)
- Net encoders (Audio)
- Net decoders (Characters)
- Command-line program (WolframScript)
- Workflows and more
Evolution of Tutorials (Tech Notes and Monographs)
Starting in Version 12.0 and continuing in 12.1, tutorial documents are being rebranded into either monographs or tech notes. Monographs are long expositions considered timeless across versions, and tend to richly explain a topic as you would see in a textbook. Tech notes generally focus solely on the implementation details of a given topic in the Wolfram Language.
Wolfram Function Repository
The Wolfram Function Repository, announced last year by Stephen Wolfram, also has its own documentation pages. In a future release, access to these pages will be fully integrated into our documentation search and cross-referencing efforts. The content is created by users like you who design their own tools that do not yet have dedicated functions. If you have custom functions, go to the website to learn how to contribute.
In Documentation We Trust
Good content doesn’t mean anything if customers can’t find or use it. While other companies are just now understanding the benefits of interactivity and runnable code examples, Wolfram pioneered them, and we’ve got three decades of computation and innovation to show for it. Where open-source projects fail to deliver meaningful docs to their users, Wolfram ensures it through tens of thousands of hours of rigorous language design reviews—and our documentation creation process directly informs that design review process. For us, documentation has been a foundational component of a good software experience for more than 30 years.
Browse our Documentation Center and try out examples, learn more about cutting-edge features and discover something new!
|Get full access to the latest Wolfram Language functionality with Mathematica 12.1.|