What do we want in the developer docs? Where do we want it?

[CharliePoole]

I'm writing this issue so we can discuss and decide the two questions in the title.

As we decide things, we can take action immediately or spawn specific issues.

Currently, with the removal of the FAQ and Vision, the developer docs have the contents shown below. The notes follow the list.

• Team Practices
  • How We Work As a Team
    • Issue Tracking
    • Pull Requests (1)
    • Contributions (1)
  • Technical Practices
    • Coding Standards
    • Best Practices for XML Documentation
    • Standard Defines
    • Adding New Projects (2)
    • Packaging the Framework (3)
    • Packaging the Console and Engine (3)
    • Packaging Extensions (3)
    • Packaging the Installer (3)
    • Packaging the V2 Adapter (3)
    • Packaging the V3 Adapter (3)

• Specifications (4)

  • Framework
    • Include and Exclude Attributes Spec (4)
    • Extended Constraint Syntax Spec (4)
    • Dynamic Test Cases Spec (4)
    • Text Output from Tests Spec (5)
    • Generation of Test Names Spec (5)
    • Parameterized Test Fixtures Spec (6)
    • Test Dependency Attribute Spec (4)
  • Test Engine
    • Engine Addins Spec (5)
  1. These could be merged into Issue Tracking. Pull Requests doesn't even exist yet.
  2. Info could be added Build.md or to a separate file in the framework root.
  3. Could go into a Packaging file in the root of each project.
  4. These are specs for features I originated, on which we have not done work. They could be removed (I would take a copy) or put under some "future" heading elsewhere.
  5. Work is done. I have been slowly creating documentation pages for these items and then removing the specification.
  6. This one is only partially done, at least as I recall.

From my notes, you can see that I favor a severely reduced developer info section - perhaps none at all. It could also be something that is reached by a separate link rather than from the main menu of the wiki.

Thoughts? @nunit/core-team @nunit/framework-team @nunit/engine-team

[jnm2]

I'm favor of 1, 2, 3, 4 under "future" group, and the general direction of source-controlling as much documentation as possible in parallel with the actual code in each repo.

[SeanKilleen]

🧹 Housekeeping: Closing this as an older issue with no discernable actionable follow-up for the docs in their current state.