New TOC?

[richlander]

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:

• Outcome based (build a lib, build an app, build an analyzer).
• Component based (Runtime, BCL, Roslyn)
• Experience based (Developing with VS, Developing on Linux)
• Difficulty based (Getting started, Advanced topics)

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]

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]

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]

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

[cartermp]

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]

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]

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]

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

• Getting started
  • Topics on installing stuff on various OS-es
• Tools and stuff
  • CLI reference
  • How to work with various editors
• New to .NET?
  • Beginner
  • Intermediate
  • Advanced
• Familiar with .NET?
  • Beginner
  • Intermediate
  • Advanced
• API
  • All kinds of reference docs with richer content and examples

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]

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]

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

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]

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]

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]

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]

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]

NOTES FROM MEETING

Top Level:

• Documents the platform + some language features
  • Most likely the "cool" ones that are selling points
• Very general-purpose
• Very limited amount of policy
• Getting Started Experience:
  • will use the new dotnet cli
• Advanced category:
  • Roslyn may deserve a paragraph
• Add more to contribution policy about vision for the doc
• Bais towards three users
  • New to .NET
  • Knows .NET, wants to do new stuff
  • Knows .NET, wants to port existing stuff

What we target for now:

• On-ramp content
• Point somewhere else right now (and hopefully not to MSDN)
  • If we want to write a conceptual doc later, we will
  • Perhaps a link to an unwritten document right now

TOC Structure:

// TODO add this with an edit