Skip to content

TOC principles - ideas and suggestions #152

Closed

Description

@thesmithee

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
  • 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

  1. BethMassi commented on Nov 20, 2015

    @BethMassi
    Contributor

    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:

    • Getting started
      • What is .NET ? (start with http://dotnet.github.io/docs/getting-started/overview.html)
      • Installing .NET Core
        • Install on Linux
        • Install on OS X
        • Install on Windows
      • Setting up your Development Environment
        • Development using Visual Studio
        • Development using Visual Studio Code
        • Development using vim
        • Development using Sublime Text
      • Writing your first console app in .NET Core
      • Writing your first ASP.NET app using .NET Core (link to asp.net docs)
    • .NET Command Line Interface reference
    • Learn C#
    • ...Lots of C# tutorials & samples..
    • Understanding .NET Core
      • .NET Primer
        • Overview of the platform + context
      • Understanding Nuget (what is it? using it. Packaging how tos below)
      • Programming Languages on the .NET Platform
        • C# , F#, VB, CLI
        • Roslyn
      • Asynchronous Programming with .NET
      • Generics
      • Language Integrated Query (LINQ)
      • … more concepts…
    • Creating web applications
      • ASP.NET -> links to docs.asp.net
    • Packaging applications
      • NuGet
    • Deploying applications
    • Porting applications between editions of .NET Platform
    • Working with data
      • Entity Framework
      • System.Data
    • Writing servers/networking
      • System.Net
      • WCF
    • Parsing formats
      • JSON
      • XML
    • Standard Library Reference
      • Library 1
      • Library 2
      • Ref docs in one place….

    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 ;-)

  2. ghogen commented on Nov 20, 2015

    @ghogen
    Contributor

    @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...)

  3. BethMassi commented on Nov 20, 2015

    @BethMassi
    Contributor

    @ghogen Great idea. I actually thought of that after I hit the comment button and stared at the TOC a while. 😄

  4. cartermp commented on Nov 20, 2015

    @cartermp
    Contributor

    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:

    1. Describe what it is and smack you with a strong value proposition about why you need to use it.
    2. Get you the artifacts you need to start writing some code.
    3. Show you how to build your first app (using the most basic of tools).
    4. Introduce some more tools that you may want to consider using.

    So I would shuffle around @BethMassi 's "Getting Started" like this (ignore naming):

    • Getting Started
      • What is .NET and why should I use it?
      • Installing (this could be one doc)
        • On Linux
        • On OS X
        • On Windows
      • How to write a console app using the most basic tooling
      • Development Environment
        • Using vs
        • Using vscode
        • Using non-microsoft editors
      • Are you a Web Developer? Check out ASP.NET! (link to it)

    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.

  5. BethMassi commented on Nov 20, 2015

    @BethMassi
    Contributor

    @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.

  6. stevehoag commented on Nov 20, 2015

    @stevehoag
    Contributor

    @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.

  7. BethMassi commented on Nov 20, 2015

    @BethMassi
    Contributor

    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.

  8. stevehoag commented on Nov 20, 2015

    @stevehoag
    Contributor

    We can easily do that - maybe just a single topic on .NET Core with links to the appropriate sections of the core docs.

  9. BethMassi commented on Nov 20, 2015

    @BethMassi
    Contributor

    I think that's a good start.

  10. mairaw commented on Nov 20, 2015

    @mairaw
    Contributor

    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

  11. stevehoag commented on Nov 20, 2015

    @stevehoag
    Contributor

    Who owns that topic?

  12. ghogen commented on Nov 20, 2015

    @ghogen
    Contributor

    @mairaw owns it.

  13. mairaw commented on Nov 20, 2015

    @mairaw
    Contributor

    I do now. Cheryl wrote it.

  14. stevehoag commented on Nov 20, 2015

    @stevehoag
    Contributor

    Seems like the logical place to link into the Core docs. It definitely needs updating, and we can probably drop the link to Curah :-)

  15. mairaw commented on Nov 20, 2015

    @mairaw
    Contributor

    It needs to be completely redone!

  16. 43 remaining items

  17. BethMassi commented on Nov 24, 2015

    @BethMassi
    Contributor

    Or did I misread and you are saying the thing MS ships is .NET Core ?

  18. ghogen commented on Nov 24, 2015

    @ghogen
    Contributor

    @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

    • Getting started with XY on the .NET Core Platform (topic contains a link to the API Ref TOC)

    .NET Core API Reference

    • System Namespace
    • System.Text Namespace
    • Etc.

    XY API Reference

    • XY.Z Namespace
    • XY.ABC Namespace

    @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.

  19. stevehoag commented on Nov 24, 2015

    @stevehoag
    Contributor

    +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

    • Getting started with XY on the .NET Core Platform (topic contains a link to the API Ref TOC)

    .NET Core API Reference

    • System Namespace
    • System.Text Namespace
    • Etc.

    XY API Reference

    • XY.Z Namespace
    • XY.ABC Namespace

    @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.

  20. cartermp commented on Nov 24, 2015

    @cartermp
    Contributor

    @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:

    • Tutorial for how to hook up an app to a SQL Database of your choice (SQL Server, Oracle, etc)
      • Maybe something about code-first or model-first if we choose to showcase EF
    • Conceptual ideas about how to get started with setting up a data model
    • etc

    EF content that should not live in our docs:

    • EF API reference
    • Advanced EF topics
    • EF configuration tactics
    • etc

    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.

  21. BethMassi commented on Nov 24, 2015

    @BethMassi
    Contributor

    @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.

  22. cartermp commented on Nov 25, 2015

    @cartermp
    Contributor

    @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.

  23. thesmithee commented on Nov 25, 2015

    @thesmithee
    Author

    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.

  24. cartermp commented on Nov 25, 2015

    @cartermp
    Contributor

    Agreed. Sounds like a good plan.

  25. BethMassi commented on Nov 25, 2015

    @BethMassi
    Contributor

    Sounds like a plan

  26. stevehoag commented on Nov 25, 2015

    @stevehoag
    Contributor

    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.

  27. matthewreily commented on Nov 25, 2015

    @matthewreily

    +1

  28. mairaw commented on Nov 25, 2015

    @mairaw
    Contributor

    +1 Something we all agree on! :-)

  29. thesmithee commented on Feb 25, 2016

    @thesmithee
    Author

    Closing this as we have a decision and TOC is in place.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    discussionIndicates issues that are being discussed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions