HTML to DITA migration checklist
for using the DITA Toolkit Migration Transform

(NOTE: This is a general list; your files may require different changes and the migration transform
might be updated to support additional features. The latest version of this checklist can be found on /xml.coverpages.org/DITA-MigrationChecklist.html)

Tidy processing

tidy -c -n -m --output-xml yes --doctype omit myfile.html

Removes DOCTYPE tag

Adds ending tags (especially the link tag)

Verifies all lists items encapsulated with <li></li>

Verifies definition <dl> lists formatted correctly

Converts a <span style=”xx”> to a style entry (inline CSS) and adds a class attribute to the span.

Removes comments (most HTML editors add comments). If you want to save the comments, you need a customization.

Other pre-migration processing (may be automated in some cases)

Topic type	Ranking	Area	Description
All	Recommended	Metadata	Remove any HTML-editor-specific or unneeded meta data. Metadata migrates to <meta> elements in the <prolog>.
All	Strongly Recommended	Short descriptions	Add a short description as the first paragraph. This paragraph should not have tables, lists, or links. This becomes the first paragraph of the topic when it is generated.
All	Required	Headings	Verify that all headings in topics are in order, are at most two levels, and are one level apart. For example, h1 and h2, or h2 and h3. Tasks can only have one heading.
All	Required	Anchor names and references	Remove special characters and blanks from anchor names.
All	Recommended	Graphics links	Verify they are in <img src=…> format. It is recommended to add <alt> text to all graphics if missing.
All	Recommended	Search title	If you want a special search title, put the search title in <title> and the topic title in <h1>. If you don’t want a search title, the h1 and title text need to match.
All	Recommended	Class attributes	If you use class attributes on certain HTML tags, you need to plan the migration, and it may require a customization.
All	Required	Manual line breaks (<br>)	Delete manual breaks either before or after migration. These are migrated as XML comment with the text: “A br tag was used here in the original source.”
All	Required	Single-sourcing	Verify that formatting is consistent in HTML and customize the migration process to retain the values.
All	Recommended	Notices .	Verify notices migrated correctly to <note> elements, which has type attribute to indicate notice severity and set notice label.
All	Required	<blockquote> elements	Determine why it is used and if not needed, remove before or after migration. If you need it, migrate, then customize. Migrates to <lq>, but not good use of DITA.
All	Recommended	<span> tag use	If using <span> for context tagging, review transform to verify the different forms of the span (such as span for bold) get migrated to the correct DITA element for you files.
All	Required	Code tagging	Verify code in procedures uses <pre> and not <blockquote> so that it migrates to <codeblock>. Code snippets within a paragraph that are tagged as <tt> migrate to <codeph>.
All	Required	Special characters	If you use UTF-8: OK If you use numeric entities (&#137;): OK If you use the character entities that are not XML entities (&mdash;): Needs verification If it is not an XML entity (&amp;, &gt;, &lt; and &quot;) it does not migrate correctly. Tidy may convert all your non-XML character entities to numeric entities.
Task	Optional	Task prerequisite	If migrating to a prerequisite element, set up customization and tagging. For example add <p class=prereq> as first paragraph, if it is a prerequisite and customize to migrate to the <prereq> element.
Task	Optional	Multiple option steps	Format multiple option steps as a nested list.
Task	Optional	Step results	If creating elements other than cmd and info, then you must customize.
Task	Required	Only one task per Task topic	If topic contains multiple tasks, must break information up into separate tasks or use the tutorial override, which allows subtasks. The Task topic type supports having only one task per Task topic.
Task	Recommended	Task results	Verify overall task result is outside of the ordered list of steps.
Task	Recommended	Single-step tasks	Verify single-step tasks are in a list with a bullet.
All	Optional	Index entries	Plan index migration.
All	Recommended	Multimedia elements	Verify that all multimedia elements are within <object> elements.

Post-migration DITA Checklist

Topic type	Ranking	Area	Description
All	Required	Valid DITA	Verify that each topic is a valid DITA topic. Some editors provide XML/DITA validations.
All	Strongly Recommended	Required Cleanup	Review and remove any items that are tagged with Required Cleanup. The migration transform did not know what to do the these constructs since they are not supported in DITA.
All	Recommended	GUI items	Verify use of uicontrol and menucascade is correct (if customized to use these elements)
All	Required	Cross References	Verify cross referenced files that are NOT in DITA do not have the .dita extension.
All	Recommended	Notes	Verify Notes elements are correct