After nearly a year of trying different ways of docs generation, we have come to a conclusion that the following docs generation workflow is to be implemented.
Backstory and problems
The main problem behind poor documentation across all our projects is that we couldn't find a great trade off on how to synchronize runnable, compilable C# examples and markdown documentation. Here are more details:
We want to have compilable, runnable examples
That means that all code examples are unit-tests that can be compiled, put under CI, run as they need to. We don't need to copy-paste code from example ti run it, we don't need to have additional setup to run an example from the documentation.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
We don't want to have disconnection between examples and documentation
Comes close to the first one, meaning that we don't want to copy-paste example from the source code into markdown files and vise-verse. Samples in documentation are disconnected from the actual code base. Additional time for sync is needed, no one likes or want this.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
All documentation and examples has to be in the current solution
With many projects, we have two strategies to author documentation:
Per-project-solution: docs are stored within current project / solution
A dedicated repo and one docs project for all solution (otherrepos)
Having a dedicated solution for docs aggregating docs across all project didn't work well. Here is why:
We have to keep dependencies in sync
We have to open up two visual studios (or other IDEs) - for current project and its docs
We loose the context, we loose additioknal infrastructure which always exists in a current project to run its unit tests and regression
We become really unhappy about all this stuff, no motivation to work on docs at all
We learnt that docs has to live within a current project / solution. That way we leverage all the infrastructure for unit tests, code run that exist for the current project, we don't loose the context of the current project and can always fix up issue while writing docs.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
Proposed docs authoring flow
All docs live within project solution
All docs leverage existing unit test infrastructure to run and compile the code
All docs examples have to be compilable
SubPointSolutions.DocsBuildTools is used for sample generation / reading
SubPointSolutions.CakeBuildTools is used for common sample index generation tasks, generating and validating Wyam web site
There is an ability to run documentation offline, with Wyam or NPM
SubPointSolutions.CakeBuildTools offers tasks to publish generated web site to Netlify
All themes are shared via NuGet packages:
SubPointSolutions.DocsBuildTools.Wyam.Theme.Docs
SubPointSolutions.DocsBuildTools.Wyam.Theme.Web
Every project has a "docs" project with reference to SubPointSolutions.DocsBuildTools and common UI theme (such as SubPointSolutions.DocsBuildTools.Wyam.Theme.Docs)
Every project docs are put under CI (docs generation index, rendering actual web site, validation)
All project documentation build is aggregated SubPointSolutions.Docs repo and project - landing page exists only in this project, the rest of the docs is pulled across all repos via sparce checkout (only view folder and its sample indexes), same theme is used for this doc, Netlify publishing is driven to dev/prod web sites via CakeBuild tools
Final aim
Docs are easy to author for everyone
No break across the authoring workflow (all CI-ed, validation in place)
No potential security issues, only sparce checkouts over defined repos
Offline builds, ability to run locally with Wyam / NPM (docker-ize in the future)
After nearly a year of trying different ways of docs generation, we have come to a conclusion that the following docs generation workflow is to be implemented.
Backstory and problems
The main problem behind poor documentation across all our projects is that we couldn't find a great trade off on how to synchronize runnable, compilable C# examples and markdown documentation. Here are more details:
We want to have compilable, runnable examples
That means that all code examples are unit-tests that can be compiled, put under CI, run as they need to. We don't need to copy-paste code from example ti run it, we don't need to have additional setup to run an example from the documentation.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
We don't want to have disconnection between examples and documentation
Comes close to the first one, meaning that we don't want to copy-paste example from the source code into markdown files and vise-verse. Samples in documentation are disconnected from the actual code base. Additional time for sync is needed, no one likes or want this.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
All documentation and examples has to be in the current solution
With many projects, we have two strategies to author documentation:
Having a dedicated solution for docs aggregating docs across all project didn't work well. Here is why:
We learnt that docs has to live within a current project / solution. That way we leverage all the infrastructure for unit tests, code run that exist for the current project, we don't loose the context of the current project and can always fix up issue while writing docs.
Not having this implemented leads to additional time waste and whole inefficiency while authoring and supporting documentation.
Proposed docs authoring flow
All themes are shared via NuGet packages:
SubPointSolutions.DocsBuildTools.Wyam.Theme.Docs
SubPointSolutions.DocsBuildTools.Wyam.Theme.Web
Every project has a "docs" project with reference to SubPointSolutions.DocsBuildTools and common UI theme (such as SubPointSolutions.DocsBuildTools.Wyam.Theme.Docs)
Every project docs are put under CI (docs generation index, rendering actual web site, validation)
All project documentation build is aggregated SubPointSolutions.Docs repo and project - landing page exists only in this project, the rest of the docs is pulled across all repos via sparce checkout (only view folder and its sample indexes), same theme is used for this doc, Netlify publishing is driven to dev/prod web sites via CakeBuild tools
Final aim