(Optional) Create a new tutorial using the DITA CMS (v2 parser)

As a UA information developer, you can use the DITA CMS to bypass some steps in the Developer Relations tutorial creation workflow, but certainly not all the steps. You need to be very familiar with the Developer Relations tutorial authoring procedures before you begin. In addition, User Assistance and Developer Relations are different entities – Developer Relations has a unique style guide, and different legal considerations. You are required to complete all mandatory tutorial authoring training before you start authoring your tutorial in DITA.

Read these training materials in sequence. When prompted for a user name and password, use 20Digital20 / 20Digital20:

(This step is for doc leads.) A 1DX markdown tutorial originates in a dedicated buildable map containing a single task topic. Create a buildable map and add one task topic. Never add multiple tasks topics. Never add concept or reference topics.

1. Create a buildable map. It is recommended that the buildable map title matches the GitHub folder name you want for your tutorial. For example: hxe-ua-starting-the-vm. Folder naming conventions were provided in your Developer Relations tutorial creation onboarding training.
2. Create a single task topic child. There are no special restrictions on the task title. (The tutorial title originates in metadata, and not in the task title.)
3. Do not define relationship tables in the dedicated buildable map.

For more information see Create a Dedicated Buildable Map in the UA Infrastructure User Guide.

Define <title>, <shortdesc>, and <prolog><metadata> as shown in Create the Task Topic in the UA Infrastructure User Guide.

The metadata block is critical as it contains mandatory values for your tutorial including tutorial navigator tags, user proficiency level, and time to complete.

The Developer Relations style guide requires steps that are narrow at the top, and wider at the bottom (pear-shaped). Steps in 1DX markdown output become accordions. The <step><cmd> tag becomes the accordion title. Accordion titles need to be short – explain in 3 to 7 words what the step is, at a high level. Your <cmd> tag must contain no more than 7 words, and must begin with an imperative.

If your step contains images, note that the image title maps to the image file name in your markdown output. Use dashes rather than underscores in image titles (which gives you dashes rather than underscores in image file names).

Note: Make sure the .PNG file has an uppercase .PNG file extension, and not a lowercase .png extension.

In step 11, you will test your markdown file using the test.js script. The test script has a very sensitive spellchecker that reports uncommon terms as spelling errors. In markdown, authors hide the “false positives” from the spellchecker by surrounding them with single backtick marks. In DITA, certain tags like <codeph>, <keyword>, <filepath> map to “surround with backticks”.

To reduce the number of test.js errors (caused by uncommon words) you’ll encounter in step 11, tag suspect terms now so they are surrounded by backticks in markdown output. For example, tag the SAP HANA, express edition default user hxeadm with <codeph>.

For a list of DITA tags that map to “surround with backticks” see Supported / Unsupported Features - Markdown 1DX in the UA Infrastructure User Guide.

Markdown tables support a limited subset of the features available in DITA tables. Some table functionality available in DITA is not supported by the markdown conversion. Ensure all tables in your task meet the markdown requirements, or you will encounter build errors due to unsupported table functionality.

See Check Tables for Markdown Compliance in the UA Infrastructure User Guide.

If you are re-using tutorial content in other output types like pdf.sap or html5.uacp, you may want to suppress markdown-only content in non-markdown outputs. Use the profile output_type="markdown_output".

See Reuse: Profiling Considerations when your 1DX Markdown Task Topic is Reused in Another Buildable Map in the UA Infrastructure User Guide.

(This step is for doc leads.) Add mandatory rendering properties, and assign the markdown.sap1dx output type to the dedicated buildable map. See Configure 1DX Markdown Output in the Project Map in the UA Infrastructure User Guide.

(This step is for doc leads.) Ensure your project map is referenced in an active project.

Build your output.

Copy the Zip file for your tutorial from the dropzone to a local folder on your machine.

Extract the Zip file and copy the folder (containing the *.md file and your .PNG files) to your local Github/Tutorials-Contribution folder.

In GitHub, test your tutorial using node test.js.

In Atom Editor, preview the tutorial. See Test 1DX Markdown Output and Push to GitHub in the UA Infrastructure User Guide.

See Test 1DX Markdown Output and Push to GitHub in the UA Infrastructure User Guide.

Go to https://www-qa.sap.com/developer/tutorials/(tutorial-folder-name).html and check the tutorial for problems.

When prompted for a user name and password, use 20Digital20 / 20Digital20

(This step is for doc leads.) If you have GitHub Publisher rights, push the tutorial from the Tutorials-Contribution repository to the Tutorials repository. This will also push the updated tutorial from the QA website to the live website.