Specific organizational scheme for Matlab documentation?

According to this thread, the hierarchical organization of headings on the Content pane is the authoritative structure of the documentation pages. The links on the information page themselves are not, and they are simply included if the linked topics are relevant to the current page in some way.

Specifically, the top half of the Content pane shows the hierarchical path to the current page. The bottom page shows either peer pages to the current page (i.e., peer nodes in the hierarchical tree) or the headings/subheadings in the current page.

How does one control whether peer pages or in-page headings are shown?

As an example of uncontrollability, Java Package Basics causes peer pages to be shown in the Contents while its child page Pass Java Objects to MATLAB causes in-page headings to be shown, i.e., it doesn't show the peer page Pass Arguments To and From Java. We know that the latter two are peer pages, not from the Content pane, nor from links to each other, but because their hierarchical paths show that they have the same parent page. It is hard to suss out the structure of the information being perused without a view of succeeding and preceding peer pages. Ideally, one could see *both* in-page headings and peer pages, as one can in the Contents/bookmarks pane of a PDF document.

Since it was hard to see the organization of the pages, I thought of trying to get the "ground truth" from the PDF document. Unfortunately (or maybe fortunately), the organization does not parallel that of the HTML pages, though much of the content is the same. For example, the MATLAB/Java information seems to be split between two documents:

• MATLAB Compiler SDK MATLAB Code Deployment Guide
• MATLAB Compiler SDK Java User's Guide

I'm not saying that the information is more penetrable if it is combined into one big collection, like the HTML pages. Just that with two bodies of information organized differently, it's hard to know which to follow in order to build up the knowledge needed.

Of the HTML vs. PDF documentation sets, which is meant to be started with, and which is meant more as a reference for veteran developers?

Furthermore, the hierarchical nodes in the HTML information do not necessarily appear in the PDF documentation. For example I searched both of the above PDFs for "Java Package Basics", and it appears in neither.

Answer 1

[Wendy Fullam]

Hi JM,

I'm the product manager for the online documentation application here at MathWorks. I'd like to be of some help, but I think I need a bit more context on what it is you're trying to do with the page heirarchy, so the team can brainstorm on possible future enhancements to address your concern.

Generally speaking, the documentation has multiple templates of content. For example: Product landing pages, category pages, concept pages, examples, and references (functions, classes, blocks, etc)

Individual concept, examples, and references

• can be linked from multiple places in the documentation
• Have an "on this page" section in the lower left nav

MathWorks generally focuses on the HTML version of the documentation, since it is visited by the majority of MATLAB users. The assumption is not that someone needs to read a bunch of pages before trying to perform a task, though. We strive to make every page easy to find and immediately helpful. If you have discovered some pages which need a stronger indicator of workflow, that is definitely something to share with the authors of those pages.

Can you share more about your workflow, so I can better understand the problem you are trying to solve?

Are you, by chance, writing your own documentation?

If you would like, you are welcome to direct message me and we can take this question offline, since it may be a bit of an edgecase for the larger answers community.

I'm happy to help however you choose to proceed.

[FM]

Thanks, Wendy....how does one take this "offline"? I visited your profile page and looked for a way to directly communicate, e.g., email or messaging of some sorts.

[Wendy Fullam]

Please email me at wfullam @ mathworks.com :) Thank you!