docs
docs copied to clipboard
nunit
Developer Info Organization
Once upon a time, what is now the "NUnit Project" (organization) was one big project. That is, there was one GitHub repository, one codebase and one set of standards or practices. That has not been so for a few years.
Initially, each project that we split off kept following the same practices. Very slowly, some things diverged but the documentation didn't follow along. I believe we need to re-think how we handle developer documentation.
One option would be to return to use of independent wikis for each project. That is, docs for users would be on the website, docs for developers in the wiki. I mention this as a fallback only, in case the reorganization below does not seem feasible.
The other option is to restructure the Developer Info section of the docs so that it's clear which docs apply to which projects. I suggest a menu structure like...
Developer Info
General
NUnit Framework
NUnit Engine and Console
VS Adapter
Extensions
etc.
The benefit of this is more for new contributors than for those of us who have been around for a while. A new contributor is inevitably working on some project and it would be nice to find all info about how to work on that project in the same place. It might also encourage us to create more documentation.
The biggest bit of work here is to decide what goes into "General." AFAIK the @nunit/core-team has never imposed any standards on projects, but maybe some can be considered as generally adopted by all the projects. We could make an initial split simply based on the content of each document - some of them refer to projects in their name while others do so in the text itself.
I think keeping this on docs.nunit.org is a good idea.
I'm not sure there is a use for a "general" section, other than perhaps to contain the current docs, with a warning that they may differ per project.
@ChrisMaddock There are some docs out there that are labeled as belonging to a certain project, so they would go under that project. There are other docs that include paragraphs or sections for different projects, I'd lean toward splitting those. Everything else is either "General" or obsolete and I think we may not all agree on which it is.
As an example of the last, take Coding Standards. Before we split, they applied to the unified NUnit Project. Do they apply to all projects now? All except those that override? No projects? The Core Team never decided after our split. It would be good to figure it out and tell contributors which it is. :smile:
I think that we should keep it on docs.nunit.org, and I think @CharliePoole's split up sounds reasonable. Regarding "Coding Standards" then I think think it is fine to have some general standards for the entire project and the some more specific per projects. For instance, we don't follow the guidelines about using declarations in the Analyzer project :)
