Wolfram Blog
Brian Van Vertloo

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.

What's New with Wolfram Docs

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.

The Documentation Center Home Page

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:

Recently Added Features page

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:

Reference page drop-down examples

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:

Icons

Opener Previews

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:

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

Link Styling

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:

Link styling

Entity page links have their own style too; they’re similar to entity pods and light up when hovered over or clicked:

Entity page links

Other link styles include package symbols (light blue) and non-Wolfram Language functions, such as WSTP C language functions (green):

Other link styles

More link styles

Workflows

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:

Related categories

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:

Horizontal breakpoints

Unique to our documentation is that we also respond to vertical breakpoints in the same way:

Vertical breakpoints

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:

Guide preview

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:

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:

Click to copy

In the same hover effect, there’s an icon providing an anchor link to that example (for later reference or ease of sharing):

Icon for hover link

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:

ImageResize example

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:

Copy entire usage template

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

Search Improvements

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.

Search results

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:

New page types

Here’s a list with examples:

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.

Tech notes

Video basics tech notes

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.

Wolfram Function Repository function

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.

Buy now

Leave a Comment

3 Comments


mpoulshock

Where would we be able to find a list of all tutorials/monographs/tech notes?

Posted by mpoulshock    March 30, 2020 at 11:20 am
    Brian Van Vertloo

    There isn’t a page that lists all of them. Many versions ago, we had a “Virtual Book” which was a kind of front-to-back read of the tutorials that were available then, but it was discontinued. Is that something like what you were looking for?

    Otherwise, if you just want to peruse what’s there, they’re all still in the same directory (for now). For an English-language product :

    FileNames["*.nb", FileNameJoin[{$InstallationDirectory, "Documentation", "English", "System", "Tutorials"}]]

    Note that this excludes any that are part of packages, but those generally remain as tutorials, not tech notes or monographs.

    If you’d prefer not to dig through the file system, you may have some luck searching in the Documentation Center for “Monograph” or “TechNote”, though the search system isn’t optimized for queries like that, so YMMV.

    Posted by Brian Van Vertloo    March 31, 2020 at 12:14 pm
      mpoulshock

      The Virtual Book you described would be ideal or even a table of contents would be great. Thanks for the other suggestions, Brian.

      Posted by mpoulshock    March 31, 2020 at 4:11 pm


Leave a comment