The Need
On a recent software adventure, I needed to assess library documentation tools. It was important to consider how they would look, how it integrates into a CI process, ease of use, VSTS friendliness, and resources needed to manage the result. There were a few options to look at, and we are looking for. Net based tools. DocFX, Sandcastle, and Vsxmd were what I found after a brief look around.
Options
-
DocFX is a tool that generates a static site based on reflection over your library.
-
SandCastle is like DocFX, but support looks questionable. It was a Microsoft product between 2006 to 2010. A single developer or small team now maintains SandCastle.
-
Vsxmd is a Visual Studio plugin that turns the XML generated from the MS Build process into markdown.
Observations
DocFX and Sandcastle both generate a static website using XML comments and reflection. They also cater to GitHub style markdown and GitHub hosting as project wikis. Without the GitHub integration you will need to host the generated site. Both are typically setup on their own CI process and do not require the developers to install anything differently unless they want to build the documentation on their own machines.
Vsxmd’s generated markdown is GitHub flavored and doesn’t work in VSTS. In addition, Vsxmd generates a single markdown file. The in document links for the file generated do not work within the VSTS environment, but with VSTS search is almost still functional.
On another note, with Microsoft gaining Github, I question the future of VSTS. Integrating Azure to Github makes me wonder how long VSTS will be viable. The 2020 MS Build conference did nothing to make me think VSTS will fit the long-term developer platform that Microsoft is building.
Static Site Generators
Pros
- Both look good.
- Both Highly customizable.
- No dev overhead.
- API docs accessed separately from source.
Cons
- Require somewhere to host.
- Documentation no longer with the source.
- Sandcastle maintenance no longer by Microsoft.
- Versions of documentation and source may not match.
- GitHub flavored markdown doesn’t work in TFS.
Vsxmd
Pros
- Built with the code.
- Markdown file available in source control.
- Easy to understand.
- Documentation matches the code.
Cons
- Happens with the build and might cause issues.
- Single file links and stuff don’t work as it is GitHub flavored.
- Ugly.
Assessment
The libraries documented are internal use. Hosting the documentation with the source in VSTS would be best, so DocFx/Sandcastle are not ideal. Vsxmd’s single markdown file lacks working links and other usability features and is also not ideal.
Proposal
DocNet! The above is the path that leads me to creating a new tool. Initially, I will write it in Rust for fun and to explore the domain. I will re-write it with C# using a similar method to DocFx/Sandcastle after I complete the learning spike. I will try to document the learning process and subsequent product development.
This project likely has a very shot lifespan as I believe VSTS will become more Githubby or go away entirely. DocNet will still be a fun project and might help other teams and especially those maintaining legacy software.
DocNet Goals
- One file per class. (links back to inherited interfaces and base classes?)
- Files linked with something like MDWiki.
- Make use of VSTS code search features to enhance the experience.
- Format not ugly. Hard to make good looking documentation. Super kudo’s to DocFx, Sandcastle, and Rust doc for making some of the best project documentation I have ever seen!