doc/articles/uno-development/doc-on-docs.md
Good documentation is essential, and writing docs is a valued contribution that makes Uno more useful for everybody. This article covers when to write docs and what you should write, with a focus on two of the most common forms of documentation: step-by-step guides (ie howtos or tutorials), and feature documentation.
We have a few different fill-in-the-blanks style templates, linked below.
For the DocFX tool used to build the docs website, see more info here.
Some useful resources on writing good technical documentation:
Step-by-step guides that address a particular problem or use case that multiple developers are likely to encounter.
Let's say you're implementing a new Uno Platform feature. Do you need to add documentation for it?
It depends.
There's two different cases:
Uno's API matches WinUI's API, and most of the time, a new Uno feature will map to an existing WinUI feature.
In this case, to the extent that the behavior you're adding is the same as the WinUI behavior, you don't need to add documentation. The existing WinUI documentation is fine. It's already linked to from Uno's reference documentation.
What if the Uno behavior deviates from WinUI behavior?
If it's just a case of part of the functionality not being implemented yet, and the developer using the corresponding type/method/event would discover that it's marked with the [NotImplemented] attribute, then that's fine - there's no need to document it further.
But sometimes the functionality can't be supported, due to intrinsic limitations of the target platform. (This is more likely to be the case with non-UI features.) And/or part of the functionality may implicitly fail to work, even though none of the entry points are marked NotImplemented.
In those cases, it's important to add documentation. Copy the WinUI feature template to the features directory (or controls directory for controls inheriting from FrameworkElement) and fill in the appropriate sections. Make sure to fill in the matrix describing which features are supported on which platforms.
Rarely, features are added to Uno Platform that aren't part of WinUI (VisibleBoundsPadding and ElevatedView are two examples). Somewhat more commonly, platform-specific functionality or options are added to an existing feature.
It's important to document these novel features when you add them, since they aren't covered anywhere else. Again, copy the Uno-only feature template here to the features directory and fill in the sections.
The Uno Platform documentation is aggregated onto https://platform.uno/docs/articles/intro.html, including some repositories that are in the unoplatform GitHub organization.
The CI includes a step to clones repositories at a specified commit or branch, and provides the path to the DocFX table of content.
To include documentation (let's take Uno.Themes as an example):
Update your documentation in Uno.Themes repository, preferably in a folder named doc
Include a file named toc.yml, using this file as a template:
items:
- name: Introduction to Uno Themes
href: ../Readme.md
Once you have merged your changes into Uno.Themes' main (or the default branch), take the commit id and place it in the doc/import_external_docs.ps1 of the uno repository, as follows:
@("https://github.com/unoplatform/uno.themes", "uno.themes", "INSERT_COMMIT_HASH_OR_BRANCH_NAME"),
Create a PR and validate that the content you added is appearing in the Uno Platform toc.yml where external/uno.themes/ is visible. Ensure href path ends by toc.yml for all nodes to be visible.