Repository navigation
Description
Overview
We all agree that our current TOC is not very good and needs improvement. It is also suffering from lack of direction and vision on what it needs to be and what it needs to outline going forward. This short writeup aims to remedy that, and provide suggestions for both the principles, as well as a sample of how the TOC could look like when those principles are applied.
This is also influenced and address some thoughts from #52 .
Goals
The overall goal of our docset should be simple: to educate new and existing users on what .NET Core is and how to create applications with it. Period.
Adding to that, our next goal should be to provide a map for new users to navigate properly through the .NET ecosystem, which, given time, will slowly migrate over to .NET Core. We now have a unique opportunity to try and set things properly vis-a-vis the richness of the overall platform and associated products. This means that we want to provide guidance to other pieces of the .NET Ecosystem that Microsoft ships when it comes to documentation.
Principles
There are several principles I think we should adopt in documentation going forward:
- Quality over quantity
- Meticulously curated
- Ecosystem and platform image
- Scenario organization first, component second
- Guided learning curve
Let's dig into every one of those.
Quality over quantity means that we don't focus on the amount of content but whether it is good or not and whether it supports the above goals. There is no need to stuff our docset with everything and the kitchen sink, it is much better to focus on those things that people have the need for in 80% of their scenarios. Also, we do have a lot of content out there, so focusing on quality first doesn't have to mean small amount of documents; for those topics that fall into 20%, we would actually direct people to existing content around the web (MSDN, CodeProject, wherever we feel the topic was best explained).
Meticulously curated means that we will always be on point to curate content and that we will not accept into the core platform documentation non-curated content. All contributions will have to follow a strict set of guidelines, both in writing and topic selection; this will apply to both community and internal contribution.
All of the documents will form an ecosystem and platform image insofar as they will allow consumers of the docset to actually envision how the platform is tied together and which pieces are part of the core platform and which are part of the wider ecosystem. In this way, we guarantee that people have a clear picture on the ecosystem and what is to be used when and how.
The docset will have scenario organization and each specific piece of it will have to fall into one to more scenarios that were identified or new ones that will be identified. This will solve several problems that I can see with the current documentation. For instance, when you go to https://msdn.microsoft.com/en-us/library/w0x726c2(v=vs.110).aspx today, you will see a mish-mash of topics. Some will be for various versions of the .NET Framework, others will be for Entity Framework for instance. There is no mention of the actual scenario each of the component enables. So, if I'm a new user, I have no idea that "Entity Framework" is something that will actually help me with data access. If we group topics by scenarios, for instance "Working with data", we could solve this problem very easily. Once inside a given scenario, it is OK to organize by component for clarity.
Overall organization of the documents should follow a guided learning curve, where first documents in a topic are aimed for beginners and last ones are aimed at advanced users. This way, we avoid having to explicitly tag documents with their "expertise level", but we also allow people a gradual introduction into any given topic.
How would this look?
OK, all of the above was fine and nice, but how do we get a decent TOC out of it? When we apply the principles to the TOC we have before us, we first see the following change: the current docset will raise and will have to include other components as well. If we apply the principle of scenario organization, we can see that additional libraries, such as System.Data or Entity Framework or WCF will be grouped by scenarios. For .NET Core, the platform and the new tooling we are building, the main scenario is building console applications. After all, these types of applications are the bedrock of everything, pretty much. Of course, I'm not talking just about the shell utilities, I'm also talking about microservices, daemons (services) etc.
So, .NET Core would be talking about the most fundamental application scenario. Within it, we would actually have components (such as StdLib and other things that are useful). Other libraries would be part of their own scenarios, for instance "working with data", "working with formats", "networking" etc. Of course, one component may fall into many scenarios depending on the need (XML can be a format but also a data storage scenario) and that is perfectly ok.
For those libraries that already have documentation, we link to them. For those that don't, they can live within our little universe. Those that want to move can move as well, provided that they formulate their documentation according to the principles above.
There are those concerns which are cross-cutting from a scenario perspective, of course. One of them is "getting started", another is "working with tools". Language tutorials also fall into this category, since regardless of the application, you will actually have a need to get the toolchain, learn the languages and figure out the higher-level tools (Visual Studio, VS Code etc.)
Taking all of the above, here is how the TOC could look like (titles are examples, please do not comment on those):
- Getting started
- Install on Linux
- Install on OS X
- Install on Windows
- Higher-level tools
- Visual Studio
- VS Code
- Vim!
- Programming languages for .NET Core
- C#
- F#
- .NET Core
- What is .NET Core?
- Overview of the platform + context
- Writing console applications
- Your first console application
- How to write console applications
- Packaging applications
- NuGet
- Deploying applications
- Porting applications between editions of .NET Platform
- .NET Command Line Interface reference
- Standard Library reference
- Lib1
- Lib2
- What is .NET Core?
- Working with data
- Entity Framework
- System.Data
- Writing servers/networking
- System.Net
- WCF
- Creating web applications
- ASP.NET -> links to docs.asp.net
- Parsing formats
- JSON
- XML
And so on. This way, the TOC could grow without losing the ability to be easily navigated, given that the number of scenarios is much smaller than the number of potential technical solutions that address the needs of those scenarios.
Activity
BethMassi commentedon Nov 20, 2015
I agree our overall documentation approach should be to get new and existing users up to speed with .NET Core. This also means looking at our valuable assets we already have built up over time on MSDN, Channel9, etc. as well. We really need to prioritize our new to .NET cross-platform developers here in core-docs because of the bias MSDN has (rightly) had to our current .NET windows developers. The content for this crowd here in this repo should be focused on understanding what the benefits of core are and how to port their existing assets. For everything else, we need to take a good look at MSDN and link there appropriately for those scenarios. We need to improve docs there too, not leave them behind.
For new to .NET we need to have a clear learning path pop from the TOC and I don't really see that here. I would strongly recommend having a "What is .NET?" in the Getting Started that positions .NET Core and .NET framework concisely. We need to answer the "Why .NET?" right off the bat. Getting Started isn't just about installing. It's about 0-30 learning.
"Higher-level tools" should be scenario focused, not an esoteric title like this IMO. "Setting Up your Development Environment" is an important scenario that should be at the top level.
"Programming Languages for .NET Core" again isn't scenario focused. This is part of understanding the whole platform. We need to have call to actions like "Learn C#" or if you wish "C# tutorials". The programming language portfolio should be described but that is part of the understanding of the platform IMO.
Your scenarios, Working with data, networking, Creating Web apps, parsing formats are great and we could link to them from the language tutorials as appropriate. Things that aren't scenario focused still have a place (I'm suggesting concepts under Understanding .NET below), I would just lean on scenarios right now as we start to prioritize content building. I would change your TOC based on the topics you propose like so:
And remember TOCs will change over time as content builds. That's a fact in my 8 years experience building content and IA for MSDN ;-)
ghogen commentedon Nov 20, 2015
@blackdwarf the principles you outline are great and ones that if articulated well in visible guidelines will help the community rally around a common vision.
@BethMassi I like your revisions to the proposed TOC and would extend your thinking to suggest moving the ".NET Command Line Interface reference". What if we introduce the command line as part of Setting up your Environment (e.g. "Setting up your command line environment"). Then put the full CLI reference somewhere that doesn't interfere with the learning flow (Install, Set up environments, learn C#, orient around .NET Core, then on to specific application types...)
BethMassi commentedon Nov 20, 2015
@ghogen Great idea. I actually thought of that after I hit the comment button and stared at the TOC a while. 😄
cartermp commentedon Nov 20, 2015
I like these principles a lot. I'm reminded of Clojure for the Brave and True, and although it doesn't have the same aim, it does such an excellent job getting new people started with Clojure that I feel like it has something to learn from.
I agree a bit more with @BethMassi on what "Getting Started" encompasses. Taking a look at what CftBaT did:
So I would shuffle around @BethMassi 's "Getting Started" like this (ignore naming):
At this point I don't really have a strong opinion about the rest of the TOC. I like @BethMassi 's approach for "Understanding .NET Core" acting as a set of things you should learn how to do pronto (and also sell some of the sexy features, like LINQ and async). However I also think that @blackdwarf 's idea about getting some of the really important info out there as early as possible (like how to port) is a good approach too.
BethMassi commentedon Nov 20, 2015
@cartermp I agree wholeheartedly with your last paragraph and @blackdwarf 's scenarios. My comments are mostly aimed at making the newbie successful quickly by proposing a natural learning plan in the TOC (not that it's the only thing there, but it should pop). Your porting docs are essential to our current devs and should also pop for that audience. I'd like to know what the MSDN peeps think about that content. How do we get the porting docs linked into MSDN? For C# tutorials, we're going to update MSDN docs in place.
stevehoag commentedon Nov 20, 2015
@BethMassi Do you think that the porting docs belong on MSDN rather than .NET Core? Or are you thinking in both places? Probably makes more sense on MSDN and linked to from Core, since newbies aren't likely to have apps to port.
BethMassi commentedon Nov 20, 2015
I'd lean the reverse actually. I expect .NET devs new to core to come here for docs relevant to them as well. I was thinking of flowing MSDN eyeballs to core-docs for these scenarios. In addition to audience, another major reason for that is because it's easier to update core-docs. For the C# tutorials, we're already capturing a ton of MSDN traffic there so back-porting our modern tutorials makes sense in that case.
stevehoag commentedon Nov 20, 2015
We can easily do that - maybe just a single topic on .NET Core with links to the appropriate sections of the core docs.
BethMassi commentedon Nov 20, 2015
I think that's a good start.
mairaw commentedon Nov 20, 2015
We have a topic for .NET Core on MSDN but it hasn't been updated recently.
https://msdn.microsoft.com/en-US/library/dn878908(VS.110).aspx
stevehoag commentedon Nov 20, 2015
Who owns that topic?
ghogen commentedon Nov 20, 2015
@mairaw owns it.
mairaw commentedon Nov 20, 2015
I do now. Cheryl wrote it.
stevehoag commentedon Nov 20, 2015
Seems like the logical place to link into the Core docs. It definitely needs updating, and we can probably drop the link to Curah :-)
mairaw commentedon Nov 20, 2015
It needs to be completely redone!
43 remaining items
BethMassi commentedon Nov 24, 2015
Or did I misread and you are saying the thing MS ships is .NET Core ?
ghogen commentedon Nov 24, 2015
@blackdwarf OK, getting away from the EF specifics.
My viewpoint is that some ported libraries will make sense to include in the .NET Core API Reference, some might not. Whether it is included or just linked to would, I would suggest, depend on how closely the library is tied to .NET Core, whether the users are mostly .NET Core users, or mainly Windows programmers with a small number of .NET Core users for a .NET Core port of a library.
Working with XY
.NET Core API Reference
XY API Reference
@BethMassi I think you and I are on the same page -- many satellite libraries would be served best by links. Some that are very .NET Core focused would or could have API ref in our TOC, and it would be a case by case choice.
stevehoag commentedon Nov 24, 2015
+1 on this viewpoint. For example, C# is a part of many .NET Core scenarios, but I wouldn't expect to see the entire C# language reference here. For a smaller library that is primarily consumed by Core, it might make sense to pull in the docs for convenience. Case by case decisions.
Sent from Outlookhttp://aka.ms/weboutlook
From: Gordon Hogenson notifications@github.com
Sent: Tuesday, November 24, 2015 12:21:19 PM
To: dotnet/core-docs
Cc: Steve Hoag
Subject: Re: [core-docs] TOC principles - ideas and suggestions (#152)
@blackdwarfhttps://github.com/blackdwarf OK, getting away from the EF specifics.
My viewpoint is that some ported libraries will make sense to include in the .NET Core API Reference, some might not. Whether it is included or just linked to would, I would suggest, depend on how closely the library is tied to .NET Core, whether the users are mostly .NET Core users, or mainly Windows programmers with a small number of .NET Core users for a .NET Core port of a library.
Working with XY
.NET Core API Reference
XY API Reference
@BethMassihttps://github.com/BethMassi I think you and I are on the same page -- many satellite libraries would be served best by links. Some that are very .NET Core focused would or could be hosted in our TOC, and it would be a case by case choice.
Reply to this email directly or view it on GitHubhttps://github.com//issues/152#issuecomment-159394414.
cartermp commentedon Nov 24, 2015
@blackdwarf I think the ref docs for a component like EF are special, because they're no longer about the .NET Core platform anymore. These are different because they're explicitly not conceptual docs, they're reference docs! Reference docs are going to cover APIs specific to EF that are so specialized that they really don't have anything to do with the overall concept of "Working with Data".
I want to make my point as clear as possible.
Content where we could bring in EF:
EF content that should not live in our docs:
There's a clear distinction here: one category is about the platform, where EF is one of many possible technologies to showcase. The other is about a particular technology, which happens to run on the platform. Reference docs are part of the second category. They document a technology, not the platform.
BethMassi commentedon Nov 24, 2015
@cartermp I was thinking for this specific case, that we would want to definitely represent the ability to work with data on the .NET Core platform by having a slot in the TOC "Working with Data" but that page would link directly to the EF 7 docs (like the top of the TOC there, wherever "there" is). The tutorials for "hooking up an app to a database" should live physically with the EF docs.
Here's the way I'm looking at it so our readers have a good experience. We want to represent the fullest set of scenarios you can achieve with .NET Core so people know what the platform is capable of doing (I think that's what @blackdwarf means by "ecosystem"). That's a lot of things. If we, say, draw the line at physically carrying only docs related to learning .NET core platform and using the base class libs then we still should represent the main-line app models (EF, ASP.NET, XYZ) built on top of core that you can use to build real applications. That representation can just be a scenario entry in the TOC with links to those docs.
In reality, we're probably going to have people approach us to carry app model documentation so we'll have to evaluate on a case-by-case basis.
cartermp commentedon Nov 25, 2015
@BethMassi I think that it's totally reasonable to have an entry in the TOC about a particular app model showing some guidance on how you can begin using it. Where I ultimately draw the line is reference documentation or other more advanced topics which go beyond demonstrating the platform and its ecosystem, and linking to them from here.
I suspect you're going to end up finding a split of sorts if you were to go out and ask developers about if they think reference docs should live in a place like this or not. Speaking personally, I always found it weird that MSDN had the reference docs for EF6 and MVC5, especially since I'd have to navigate back and forth between something like the ASP.NET Identity guide and the MSDN reference docs for the API I was using.
thesmithee commentedon Nov 25, 2015
Ok I think we will not come to an agreement on this here. I for one dont find anything "advanced" in ref docs per se so I fail to see how are those things, situated properly, against "demonstrating the platform and ecosystem".
However, since we have work to do I suggest we take what we agree on, which is the .NET Core core content and get cracking. I will make a PR for a new TOC tomorrow that covers only that. I also suggest we revisit this topic (scenarios and such) when we have the core stuff done to a point and see how to proceed.
cartermp commentedon Nov 25, 2015
Agreed. Sounds like a good plan.
BethMassi commentedon Nov 25, 2015
Sounds like a plan
stevehoag commentedon Nov 25, 2015
Yes, let's do it...
Sent from my Windows Phone
From: Beth Massimailto:notifications@github.com
Sent: 11/24/2015 8:28 PM
To: dotnet/core-docsmailto:core-docs@noreply.github.com
Cc: Steve Hoagmailto:Steve.Hoag@microsoft.com
Subject: Re: [core-docs] TOC principles - ideas and suggestions (#152)
Sounds like a plan
—
Reply to this email directly or view it on GitHubhttps://github.com//issues/152#issuecomment-159488780.
matthewreily commentedon Nov 25, 2015
+1
mairaw commentedon Nov 25, 2015
+1 Something we all agree on! :-)
thesmithee commentedon Feb 25, 2016
Closing this as we have a decision and TOC is in place.