Restructure of top-level table of contents

[ChrisMaddock]

This is something that's been on my radar for a while. I'd like to restructure the "NUnit" section of the docs to better reflect the different products it now spans. My thoughts:

• This structure predates the break up of the different projects, and reflects NUnit 2's technical structure, when there was less of a divide between the primary components.
• I want to make sure the docs to better separate out the framework, engine, console, NUnitLite runners, and NUnit Engine extensions. I'd hope this will make things clearer to end users that they are dealing with multiple products, of which they will likely be using at least two.
• I'd like to make the content more approachable for new users - highlight the 'every-day' stuff over the more advanced functionality.
• I'd like to better draw out the engine content, as it's own tool for users to work with.

I was thinking of looking at this after docfx was in place, but now I'm wondering if it's maybe better before. Reasons:

1. Looking at the current URL structure, it'll involve changing URLs. Docfx will handle the redirects, but given we're just about to change all the URLs anyway, it would be nice to avoid a second level of redirection.
2. Given this looks like it's going to be a bit of a "relaunch" for our docs, it would be good to get things structured in the right way from the start.

@SeanKilleen - what do you think? I can help with this, providing we can hold on till next weekend!

[ChrisMaddock]

Here's a rough bash at a new structure, to replace the top-level "NUnit" section. Not all pages included. I'd expect some of the pages that are currently more general e.g. "Usage Notes" and "NUnit Internals" to be broken up into their separate projects.

Overview
	Introduction
	Getting started (to cover both netfx and netcore)
	Upgrading
        Samples
        Architecture

NUnit Framework
	Attributes
	Assertions
	Constraints
	Dynamic tests (rename)
		TestCaseData
		TestFixtureData
	[SetUp] and [TearDown]
	TestContext
	Advanced functionality
		Assumptions
		Multiple Asserts
		Warnings
		ListMapper
	Extensibility
		Action Attributes
		Custom Asserts
		Custom Attributes
		Custom Constraints
	Legacy functionality
		AssertionHelper


NUnit Console
	Overview & Packages
	Command Line
	Options extensions (to link to Engine pages)
	
	
NUnit Engine
	Overview
	Test Engine API
	Writing Engine Extensions
	Packaged Extensions
		.nunit Projects
		etc

[SeanKilleen]

@ChrisMaddock In general, I like this idea.

However, this project was designed to be a port of the existing docs to a new structure. I am concerned that updating all of these documents and re-structuring will end up taking a lot more time and discussion, so unless the core team is unanimously on board with these changes already, my goal is to get these docs public ASAP so we can begin iterating and they don't diverge too far from the wiki.

Since we'd already be talking about delaying a week to make these changes, my gut instinct is to keep this for discussion after the conversion and deal with the redirects (which do not seem problematic to me).

[ChrisMaddock]

That sounds good to me. 😊

[CharliePoole]

@ChrisMaddock this would be easy enough to do in the current wiki, and I'd be willing to do it.

However, Sean would need to do some work to update the new site with the changes and that may make it a bad idea... I'll defer to you two.

@SeanKilleen The Core Team won't be involved in structuring the documentation. Like I said, they are analogous to a corporate board of directors... projects are run by project leads and teams.

So, Chris and Rob (his project is affected here) could make the decision and I could carry it out in the wiki in a few hours. How would that affect your schedule?

[OsirisTerje]

@ChrisMaddock You say the URLs will then be changed for all wiki content. Doesnt that creates the same issue for all external links? We should not do changes now that causes a lot of 404s. So, if this is done for the new docfx site, then it will be fine, as all wiki content then has redirection notes for going to wherever the new info is. If it changes the existing wiki, then how do we handle the 404s ?

[Update]: Noticed the "Icebox"'ing now... So this is done after conversion, and I am not worried..... And just for saying, I like the thinking of the new structure :-)

[CharliePoole]

@OsirisTerje Changes in the wiki itself would not need forwarding. The wiki appears as a flat set of pages, e.g. https://github.com/nunit/docs/wiki/Tips-And-Tricks is nested within the repo but not in terms of it's URL. That's why I suggested doing it before conversion.

However... it's only worthwhile doing it ahead of time if @SeanKilleen has time to port the updates before we go live. Sean, what are the pros and cons of delaying till we like the structure?

[SeanKilleen]

@CharliePoole per my response above, I prefer to wait unless anyone strongly objects.

[CharliePoole]

That's fine... just trying to give options and you had only expressed a desire not to wait a week, which seems like a very large overestimate of what it takes to me. I can find something else to keep me busy. :grin:

[SeanKilleen]

Hey all,

FYI, I see this as being able to proceed now -- feel free to take a crack at it in a PR. As long as Chris & Rob are good with the PR, I'll merge it in.

[SeanKilleen]

And as a side note, if you think it's important but would like me to execute it, let me know and I can do so once I have bandwidth (some work constraints around that currently.)

[ChrisMaddock]

Hi Sean - sorry, totally missed your last posts on here. I do (personally) think this would be good to sort out, and any help would be much appreciated - thank you! 😊 I’ll try and do what I can soon to get things moving, I think this one might be better done in chunks.