Writing API documentation

This section contains high-level guidance that you can use to get started writing API documentation. For full, Documentation Standards compliant guidance, refer to API documentation.

PMDT uses XMLDoc which is parsed through DocFX to create and generate API script reference documentation.

You can use Markdown syntax inside the XML tags.

See Microsoft's documentation on XML documentation comments for more information. You need to take Microsoft's information with a "grain of salt," though. The only standardized aspect is that the comments must be valid XML. Beyond that, it is up to each processor (tool, compiler, etc) to handle the various elements as they see fit. So there are conventions, but not rigid standards, which means interoperability across different tools can be inconsistent.

What to write

Your goal is to be clear, concise, and accurate.

However, let the tech writer worry about the phrasing. Your main job is to identify the necessary information.

Our audience of developers want to know the following for each type and member:

• What is this thing?
• Why would I use it?
• When would I use it?
• How would I use it?
• What can go wrong?
• What other things does this relate to?

Depending on the XML tag you are writing, the recommended format changes. For templates on how to write different APIs refer to Examples of C# API documentation

For information on tone of voice and styling, refer to Tone and audience.

More resources

Slack:

• #ask-docs
• #docs-style-guide
• #docs-packman

Unity:

• In depth Scripting API style guidelines
• Unity Doc Style Guide

External:

• DocFX XMLDoc support
• DocFX Markdown support
• Microsoft XMLDoc tutorial with examples