Skip to main content
Pure Technical Services

INTERNAL: How to Create a Quick Reference Page

Currently viewing public documentation. Please login to access the full scope of documentation.

The Quick References page is a place for customers who want to find links to everything they need to know about <insert topic> can go. This can be a VMware product (Site Recovery Manager), a feature (Virtual Volumes), or an integration (vSphere Plugin). 

The basic structure is that each quick reference is a single page. No content is created in that section. Nor should we be hardlinking anything. More on that in a bit. The structure of the page is as follows:

Important information at the top (advisories, requirements/recommendations). This can has some flexibility and is up to the author.

Note a template for creating new Quick References can be found here: https://support.purestorage.com/Solutions/VMware_Platform_Guide/Quick_Reference_by_VMware_Product/Template_Quick_Reference Clone it and edit.

Managing Content Lists with Tags

We do not want to have the manual update links, nor manually enter links, therefore this will be controlled by tags. Under each section complete the following process:

NOTE: Inserting deki script only needs to be inserted into the quick reference. For content, just apply the mindtouch tags as appropriate

1) Insert Deki Script:

clipboard_e16a69f59b3d6c089994fe0ed2e78342d.png

You will see the following appear:

clipboard_e4bfa356801c381c7fe2d2cff77fe9825.png

Paste the following code in the the black "Enter DekiScript" box:

var query = "tag:tag__security_sales";
var pages = wiki.getSearch(query, 100, "-date");<div class="widget-tagged-articles">
    <ul>
        foreach (var pg in pages)
        {
            <li>
                <a href=(pg.uri)>pg.title</a>
                <span class="date">
                    " ( updated ";
                        date.format(pg.date,"ddd MMM dd, yyyy");
                    " )"
                </span>
            </li>
        }
    </ul>
</div>

On the first line is all that you need to change. Change the information under tag (the above shows tag__security_sales). Replace that with your tag. It is imperative we follow consistent naming conventions for our tags.

Tagging Articles

We will use the following format: vpg_<product name>_<content type>.

VPG stands for VMware Platform Guide. Product name would be like vvol, or srm, or vcf. What makes sense for your topic. Content type should be one of: guide, video, howto, troubleshooting, releasenote. If you need a new one (different content type) ensure you add it to this list.

So all guides you would like to include under vVols, add the tag vpg_vvol_guide.

Would look like this:

clipboard_eac98cdffe55d4c133f14088fd5418d1e.png

Tag guides that are relevant with this tag. A piece of content might be relevant for more than two, so for the SRM user guide it can be tagged with both vpg_vvol_guide and vpg_srm_guide

For them to show up, you must tag the article. 

clipboard_e80aa51b3e47d8680e817e3f07011fd35.png

The content (and their most recent update date) will automatically appear in the appropriate sections.

clipboard_ec1275fa9fe7cbe88ba91bff58a7b6daf.png

Tagging Syntax

There are three parts of the tag syntax:

  • Prefix. For VMware this will always be vpg_
  • Topic. This will depend on the topic. vvol_, srm_, etc.
  • Collateral type. releaseNote, guide, etc. These will always be singular.

Topic Syntax Glossary

Topic Syntax (will use guide as an example collateral type for all, topic type in bold)
Virtual Volumes (vVols) vpg_vvol_guide
Site Recovery Manager (SRM) vpg_srm_guide
Pure Storage Plugin for the vSphere Client (vSphere Plugin) vpg_vsphereplugin_guide
vRealize Orchestrator (vRO) vpg_vro_guide
vRealize Operations Manager (vROps) vpg_vrops_guide
NVMe-oF vpg_nvme_guide
iSCSI vpg_iscsi_guide
ActiveDR vpg_activedr_guide
Fibre Channel vpg_fc_guide
VMFS vpg_vmfs_guide
VMware Cloud Foundation (VCF) vpg_vcf_guide
vRealize Log Insight  vpg_vli_guide

Collateral Type Syntax Glossary

Collateral Type Syntax (using vvol as an example topic for all, collateral type is in bold)
User Guide vpg_vvol_guide
Release Notes vpg_vvol_releasenote
Videos vpg_vvol_video
Troubleshooting

vpg_vvol_troubleshooting

How-Tos vpg_vvol_howto

If a collateral type is missing, please choose a name and add it to this table.

 

Sections are below as follows

The first step is to add a table to the top of the Quick Reference Guide pointing to the following:

  • A link to applicable slack channel in code-purestorage.slack.com.
  • A link to the GitHub page on Pure Storage Connect (we are labeling it "Request New Feature" so customer's go there and provide feedback).
  • A link to the VMware Compatibility Guide for the product you are creating the guide for.
  • A link to the VMware Solutions Exchange where they can download the product. If it is not applicable simply put "N/A" in the "Link" field.

Screen Shot 2020-07-31 at 12.32.40 PM.png

User Guides

This links to the various user guides that are relevant for that integration. A single user guide can be linked to more than one quick reference. This is controlled by tags. Tags should be in the format of vpg_<topic>_guide.

Example: vpg_vvol_guide

All guides should be posted here:

User Guides for VMware Solutions

Though occasionally we might want to link to guides outside of the platform guide--that is okay, just ensure it is tagged not manually linked.

Release Notes

Not all quick references will have this section. This links to the various release notes that are relevant for that integration. A single release note can be linked to more than one quick reference if appropriate. This is controlled by tags. Tags should be in the format of vpg_<topic>_releasenote.

Example: vpg_vvol_releasenote

All release notes should be posted here:

Release Notes for VMware Solutions

Though occasionally we might want to link to release notes outside of the platform guide--that is okay, just ensure it is tagged not manually linked.

Videos

This links to the various video pages that are relevant for that integration. A single video page can be linked to more than one quick reference if appropriate. This is controlled by tags. Tags should be in the format of vpg_<topic>_video.

Example: vpg_vvol_video

All videos should be embedded here:

Videos for VMware Solutions

Though occasionally we might want to link to videos outside of the platform guide--that is okay, just ensure it is tagged not manually linked. For instructions on creating/uploading videos refer to the the following KB article: <TO BE WRITTEN>

How To's

This links to the various how-to articles that are relevant for that integration. How To's differ from guides as they are specific use cases that are smaller in scope and not needed in a larger guide. A single how-to can be linked to more than one quick reference if appropriate. This is controlled by tags. Tags should be in the format of vpg_<topic>_how-to.

Example: vpg_vvol_howto

All How-To's should be created here:

How-To's for VMware Solutions

Though occasionally we might want to link to how-to's outside of the platform guide--that is okay, just ensure it is tagged not manually linked. 

Troubleshooting

This links to the various troubleshooting articles that are relevant for that integration. Troubleshooting articles differ from how-to's as they are about what to do when encountering an unexpected problem, not walking through some desired workflow. A single troubleshooting article can be linked to more than one quick reference if appropriate. This is controlled by tags. Tags should be in the format of vpg_<topic>_troubleshooting.

Example: vpg_vvol_troubleshooting 

All troubleshooting articles should be created here:

Troubleshooting for VMware Solutions

Though occasionally we might want to link to troubleshooting articles outside of the platform guide--that is okay, just ensure it is tagged not manually linked.