{"action":"created","issue":{"url":"https://api.github.com/repos/dotnet/core-docs/issues/152","labels_url":"https://api.github.com/repos/dotnet/core-docs/issues/152/labels{/name}","comments_url":"https://api.github.com/repos/dotnet/core-docs/issues/152/comments","events_url":"https://api.github.com/repos/dotnet/core-docs/issues/152/events","html_url":"https://github.com/dotnet/core-docs/issues/152","id":117934359,"number":152,"title":"TOC principles - ideas and suggestions","user":{"login":"blackdwarf","id":3115004,"avatar_url":"https://avatars.githubusercontent.com/u/3115004?v=3","gravatar_id":"","url":"https://api.github.com/users/blackdwarf","html_url":"https://github.com/blackdwarf","followers_url":"https://api.github.com/users/blackdwarf/followers","following_url":"https://api.github.com/users/blackdwarf/following{/other_user}","gists_url":"https://api.github.com/users/blackdwarf/gists{/gist_id}","starred_url":"https://api.github.com/users/blackdwarf/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/blackdwarf/subscriptions","organizations_url":"https://api.github.com/users/blackdwarf/orgs","repos_url":"https://api.github.com/users/blackdwarf/repos","events_url":"https://api.github.com/users/blackdwarf/events{/privacy}","received_events_url":"https://api.github.com/users/blackdwarf/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":13,"created_at":"2015-11-19T23:42:02Z","updated_at":"2015-11-20T01:40:56Z","closed_at":null,"body":"Overview\r\n--------\r\n\r\nWe 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. \r\n\r\nThis is also influenced and address some thoughts from #52 . \r\n\r\nGoals\r\n-----\r\n\r\nThe 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. \r\n\r\nAdding 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. \r\n\r\nPrinciples \r\n----------\r\n\r\nThere are several principles I think we should adopt in documentation going forward:\r\n\r\n* Quality over quantity\r\n* Meticulously curated \r\n* Ecosystem and platform image\r\n* Scenario organization first, component second\r\n* Guided learning curve\r\n\r\nLet's dig into every one of those.\r\n\r\n**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). \r\n\r\n**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. \r\n\r\nAll 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. \r\n\r\nThe 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. \r\n\r\nOverall 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. \r\n\r\nHow would this look?\r\n--------------------\r\n\r\nOK, 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. \r\n\r\nSo, .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. \r\n\r\nFor 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. \r\n\r\nThere 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.)\r\n\r\nTaking all of the above, here is how the TOC could look like (titles are examples, please do not comment on those):\r\n\r\n* Getting started\r\n    * Install on Linux\r\n    * Install on OS X\r\n    * Install on Windows\r\n* Higher-level tools\r\n    * Visual Studio\r\n    * VS Code\r\n    * Vim!\r\n* Programming languages for .NET Core\r\n    * C# \r\n    * F#\r\n* .NET Core \r\n    * What is .NET Core?    \r\n        * Overview of the platform + context\r\n    * Writing console applications\r\n        * Your first console application\r\n        * How to write console applications\r\n    * Packaging applications\r\n        * NuGet\r\n    * Deploying applications\r\n    * Porting applications between editions of .NET Platform\r\n    * .NET Command Line Interface reference \r\n    * Standard Library reference\r\n        * Lib1\r\n        * Lib2\r\n* Working with data\r\n    * Entity Framework\r\n    * System.Data\r\n* Writing servers/networking\r\n    * System.Net\r\n    * WCF\r\n* Creating web applications\r\n    * ASP.NET -> links to docs.asp.net\r\n* Parsing formats\r\n    * JSON\r\n    * XML\r\n    \r\nAnd 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. "},"comment":{"url":"https://api.github.com/repos/dotnet/core-docs/issues/comments/158254584","html_url":"https://github.com/dotnet/core-docs/issues/152#issuecomment-158254584","issue_url":"https://api.github.com/repos/dotnet/core-docs/issues/152","id":158254584,"user":{"login":"mairaw","id":12971179,"avatar_url":"https://avatars.githubusercontent.com/u/12971179?v=3","gravatar_id":"","url":"https://api.github.com/users/mairaw","html_url":"https://github.com/mairaw","followers_url":"https://api.github.com/users/mairaw/followers","following_url":"https://api.github.com/users/mairaw/following{/other_user}","gists_url":"https://api.github.com/users/mairaw/gists{/gist_id}","starred_url":"https://api.github.com/users/mairaw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/mairaw/subscriptions","organizations_url":"https://api.github.com/users/mairaw/orgs","repos_url":"https://api.github.com/users/mairaw/repos","events_url":"https://api.github.com/users/mairaw/events{/privacy}","received_events_url":"https://api.github.com/users/mairaw/received_events","type":"User","site_admin":false},"created_at":"2015-11-20T01:40:56Z","updated_at":"2015-11-20T01:40:56Z","body":"I do now. Cheryl wrote it."}}