search

dotnet / docs

This repository contains .NET Documentation.
https://learn.microsoft.com/dotnet
Creative Commons Attribution 4.0 International
4.24k stars 5.88k forks source link

New TOC? #52

Closed richlander closed 8 years ago

richlander commented 8 years ago

Was looking at the TOC at RTD: http://dotnet.readthedocs.org/en/latest/index.html.

I'm wondering if we want to re-think the TOC. It feels a little too fine-grained at the top and not quite thematic enough. I'm thinking (out loud) that we could adopt these approaches:

I'm sure that there are more of these. Right now, we've got a combination of these. I'm not advocating some purist approach, just that we should decide what our primary approach is for the TOC and bias more towards that.

I'm writing a new doc #46. It wasn't clear to me where that should go in the TOC or if it even appropriate for it to be a doc by itself. Thematically, it is more "outcome based". That isn't to suggest that we should go with outcome based as our plan.

/cc @blackdwarf, @cartermp

blackdwarf commented 8 years ago

The doc in question should go into the "Porting applications" part of the TOC. Besides that, I'm fine with the proposal. Some pieces of your proposal are already in there in some way. For instance, there are planned sections for working with various editors and so on. The idea was always to have these kinds of documents in there.

I would rather go with outcome based and/or experience based then component based. Difficulty can, and should be another axis that can be part of the document itself. I.e. each document can be tagged with "begginer", "advanced" etc.

richlander commented 8 years ago

I thought of "porting". This isn't porting. Assume you are starting from scratch. Porting is a really a subclass of "new development" in this case, IMO.

blackdwarf commented 8 years ago

Errr...sorry, cold is making me dense. Don't uderstand it?

cartermp commented 8 years ago

I like the idea of a new TOC. I think some mixture of Difficulty based and Outcome based is probably the best in terms of value we can provide. Components can be their own (large) part of the TOC:

...
/Componenets
|__Runtime
   |__intro-to-runtime.md

What I think needs to be done is designing the first-time use experience. My own idea is having the front page be some sort of landing page which provides guidance based on a user's intent:

I want to...

   Learn about .NET

   Read about .NET components  

   Build an app, library, or analyzer

Assuming that were the landing page, then a potential TOC would have three main sections (with subsections as appropriate):

About .NET
.NET Components
Building with .NET

I also like @blackdwarf 's suggestion about tagging articles, but it should also have some kind of organization. Under Building with .NET, for example, writing an analyzer would probably fall under a /advanced region in the docs tree.

blackdwarf commented 8 years ago

So, it would look, in general, like this @cartermp :

/About
|_ begginer/
   |_ installing/
|_ intermediate/
|_ advanced/
   |_ build-from-source/

Or, we can take a look at how other platforms do it and how their documentation is structured (https://docs.python.org/3/, http://perldoc.perl.org/, https://www.ruby-lang.org/en/documentation/). It seems that they all have a mix of content, ranging from begginer (tutorials, getting started, etc.) to advanced (language reference manuals etc.) Their "landing pages" for documentation are actually a buffet-like collection.

We don't have the landing page currently, but we could make one soon.

cartermp commented 8 years ago

The python docs you link to are for a specific version. The general Python docs landing page are much more focused, and a good example to follow.

After that I find it difficult to compare. Because each of those are for a single language, they can tailor it towards learning the language. The task their docs fulfills is simpler, so they don't need to be as organized. Since we're a platform which encompasses more than one language, I believe we'll need a focused TOC. Currently it feels moves from outcome-based (getting started) to component based (.NET Primer), back to outcome-based (tutorials, developing/porting/deploying), back to component-based (NuGet, programming languages, BCL), general topic (async), then Advanced Topics. Perhaps a landing page which guides someone to the right pieces of the TOC would be helpful, but I still think its organization is flawed and deserves a redesign.

blackdwarf commented 8 years ago

First, I would like us to stop pointing at the current TOC and make general statements like "it needs to be fixed" and similar. Yes, it does need fixing and yes, it is not the best TOC out there. This is a very trivial truth, so no use writing it. On top of that, nobody is making a statement that it should stay, so constantly saying it is kind of pointless.

Moving on, I think we are starting from the wrong side of this problem, so to speak. Let's first see what and then how, that is, let's first determine what is this, .NET Core oriented docset, supposed to document and elucidate (and to whom) and then figure out the best way to structure information.

@cartermp mentioned that all of the platforms I've suggested to look at have a single language, and thus have an easier job than we do, seeing as how we support multiple languages on .NET Core. This makes sense, since we are not even sure what languages will make their home on this docset, given the fact that some are already well documented on other Microsoft properties (MSDN) and others have their own communities that have done a stellar job so far (F#). So, it we are to take this argument to its logical conclusion, it would mean that we should focus on documenting the platform first and then worry about other things. I, for one, wholeheartedly agree with this approach.

Let's take a look at NodeJS. Although Node is also "language-specific" insofar as it only supports JavaScript (though you could make a point that anything that can be compiled down to JS can run on it), it is first and foremost a platform, and they do not really espouse the language angle on their online properties. Given this, I guess it is fair to take as an example for what we want to do. Node's docs are on https://nodejs.org/en/docs/. It seems that they consider rich API reference to be the "docs". It makes sense. Most of the people who want to use a given platform will want to understand what the platform is at a very basic level and then proceed to figure out what the platform can do, which effectively means perusing the API reference. So, it make s sense one big chunk of our future TOC could/should be the reference documentation.

Let's add two main consumer groups that we can envision consuming this docset:

  1. Users new to .NET
  2. Users familiar with .NET

Common ground for both groups is how to get started with the platform, that is, how to get and install the bits, how to use the available tooling and how to write very simple programs to kick the tires (think Hello World), as well as how to properly distribute their work to other people in two main forms (applications and libraries).

In addition to the above, I would imagine the first group would want to understand what is this platform and what are the main moving pieces, at least from 10k-foot view. So, something akin to the .NET Primer still seems like a viable thing. We should probably change it a bit though.

The second group would want to understand what are the differences between what they are used to (the full .NET Framework) and .NET Core as well as what are the steps to port their code over, should they want to.

So, the first focus point is the users' familiarity with the platform. Second one could be the difficulty of the task they are embarking on. The API reference documentation and general installing and CLI reference documentation are common. This leads us to the following potential TOC structure (shortened for ease of consumption):

This leaves out some things, at least for me, like Roslyn. I'm not sure I would put Roslyn in here, because it is a very special piece of tech, with very special interest required to delve deep into it. I would imagine 95% of our users to be perfectly content treating Roslyn as the black box that transforms source code into IL/something else. You also don't need to understand how Roslyn works to be able to use the platform even up to the Advanced level.

@richlander, @cartermp, @bethmassi, @mairaw thoughts?

cartermp commented 8 years ago

I like that potential TOC structure a lot.

I agree about Roslyn, and I'd also add that something like Async Programming may also be tough to fit in there. I'd initially think it would belong in the "New to .NET" category, but there could be devs who are familiar with .NET but haven't written async code before. Certainly not the same scenario as Roslyn as it's a much less specialized area, but it feels cross-cutting to me.

Perhaps a category after "Familiar with .NET" and before "API" is appropriate here, with its own Beginner/Intermediate/Advanced tiers? Or maybe another way to organize that category would be better? I like the consistency of having tiers for something like that, but the variety of things that could go in there may make it awkward to fit into that type of structure.

blackdwarf commented 8 years ago

@cartermp that is a valid question. There are, essentially, two ways of looking at that particular problem, IMHO.

The first one is to follow the principle that I tried to outline in the (rather long) issue above: is async a platform or a language feature? Dependent on this, it is easy to see whether it should go in or not. If it is a language feature, then it should not go into these docs, since we said above that we are documenting the platform first.

If we want to ignore this principle, then we can look at it in the second way. It is, I think, critical to understand that we already have a bunch of documentation out there for these (and similar) concepts. This docset is not supposed to replace MSDN documents, but rather to help users understand .NET Core. We will have some overlap with MSDN content because of new users, and that is fine. But we could say that the existing users (users who are familiar with .NET) can already find these docs on our existing properties. Looking at the problem this way, the "Async Programming" should go into the "New to .NET" category.

BethMassi commented 8 years ago

I like the proposed TOC but I'd steer away from labels like "Beginner, Intermediate, Advanced". Based on my experience it's really subjective once you get past Beginner.

mairaw commented 8 years ago

I agree with @BethMassi. Also, why are we documenting some general concepts here like Async? Is the idea to keep the customers in one place, so they don't get lost in MSDN? I vote for getting started/introductory materials + task-based (outcome based) TOC.

cartermp commented 8 years ago

Talked with @blackdwarf today and it would definitely be great to have a meeting where we can really nail down the purpose of these docs. When we have a strong stated purpose, the TOC structure will come naturally. We also mentioned keeping that conversation visible (either in this thread or on a new one that was opened up). Thoughts?

blackdwarf commented 8 years ago

Yep, as @cartermp mentioned, I really think we should first determine the point of the docs, as I previously stated in my (essay-ish) issue above. Anything else will, essentially, make us run in circles.

@mairaw documenting some things like async would only make sense for the people new to .NET. Even then, I would leave the topics light and introductory and provide links to more in-depth, existing content on MSDN or elsewhere.

BethMassi commented 8 years ago

Goal #1 is to provide information for new users to .NET Core. We're assuming that means new to C# as well. Happy to chat further.

cartermp commented 8 years ago

NOTES FROM MEETING

Top Level:

What we target for now:

TOC Structure:

// TODO add this with an edit

blackdwarf commented 8 years ago

Good summary @cartermp. There was also one thing that we missed and that is that this docset will, most likely, be a home for many other .NET Core components. With that in mind, in addition to the above TOC we, I think, need to add the component section when the need arises, that is, we need to plan for it. Each component would be the purvey of their respective teams.

So, the plan becomes effectively this:

Thoughts?

BethMassi commented 8 years ago

I don't think "components" is the way to think about it, that seems too narrow. I think we should think about scenarios. Most likely people are going to run into pain points or request docs based on scenarios. I think we need to just be flexible with the TOC as we start getting content for these. If we are clear about who/what the document is for in the opening paragraph, that will work for anyone that lands on it.

BethMassi commented 8 years ago

Here's my stab at a TOC that groups Getting Started, .NET Concepts, Language Tutorials, common scenarios, and reference documentation logically.

This allows us the flexibility of the scenario-focused docs as well as having a good place for deeper .NET concepts, and language tutorials. Thoughts?

stevehoag commented 8 years ago

Looks good to me. I'm guessing we'll also want "Learn VB" and "Learn F#" nodes at some point.

Sent from Outlookhttp://aka.ms/weboutlook

From: Beth Massi notifications@github.com Sent: Wednesday, November 18, 2015 4:46:32 PM To: dotnet/core-docs Subject: Re: [core-docs] New TOC? (#52)

Here's my stab at a TOC that groups Getting Started, .NET Concepts, Language Tutorials, common scenarios, and reference documentation logically.

This allows us the flexibility of the scenario-focused docs as well as having a good place for deeper .NET concepts, and language tutorials. Thoughts?

Reply to this email directly or view it on GitHubhttps://github.com/dotnet/core-docs/issues/52#issuecomment-157911157.

blackdwarf commented 8 years ago

Yes, this looks good. As soon as things die down for me a bit, I will apply what I mean in principles above and moduify this. I was thinking one level higher in the overall TOC, beyond the .NET Core and more into the overall platform.

cartermp commented 8 years ago

Looks good to me too. My only nit is that I'd move "Using Docker with .NET Core" underneath "Writing your first ASP.NET app using .NET Core" because it feels like more a of a natural next step.

BethMassi commented 8 years ago

@blackdwarf I'm interested in what you're thinking. I captured the overall platform in the "Understanding .NET" section which I don't think should be a prereq to getting going and building apps.

blackdwarf commented 8 years ago

@cartermp @BethMassi I would actually leave docker out of this untill we have a good grasp on microservices story.

I mean "ecosystem". Typo. :)

cartermp commented 8 years ago

@blackdwarf We already have a good docker story!

:D

BethMassi commented 8 years ago

@blackdwarf and ASP.NET already has docs on how to do it for them :smile:

BethMassi commented 8 years ago

@blackdwarf do you want me to submit a PR for this?

blackdwarf commented 8 years ago

@BethMassi pls wait until I write this thing I need to write out and post here, and then we will merge the two things and submit the PR. Sounds ok?

BethMassi commented 8 years ago

OK, I'm not sure what you mean by "ecosystem" in your comment above. I feel strongly that at least some of these need to be at the top level. Like the Get Started.

blackdwarf commented 8 years ago

I've created a new issue for a proposal that I have at #152 . Feel free to take a look and comment over there.

SF-Alain commented 1 year ago

Sorry if I bother… My name is Alain. Being currently based in Paris France, I used to leave in SF for a long while. Loved it, and still do! As I’m currently super passionate about programming and currently focusing on JavaScript. I wonder if someone could suggest a online net even I could join-in. If you do, please know that my current JavaScript experience and knowledge is extremely limited, however I'm super-duper passionate. Any recommendations or things, and place to virtually check? In advance, Thank you!! Be well :-)

mairaw commented 1 year ago

@SF-Alain check out our community resources at https://dotnet.microsoft.com/en-us/platform/community and our Live TV schedule at https://dotnet.microsoft.com/en-us/live