Skip to content

New TOC? #52

Closed
Closed

Description

@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

Activity

  1. thesmithee commented on Oct 12, 2015

    @thesmithee

    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.

  2. richlander commented on Oct 12, 2015

    @richlander
    MemberAuthor

    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.

  3. thesmithee commented on Oct 12, 2015

    @thesmithee

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

  4. cartermp commented on Oct 15, 2015

    @cartermp
    Contributor

    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.

  5. thesmithee commented on Nov 5, 2015

    @thesmithee

    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.

  6. cartermp commented on Nov 6, 2015

    @cartermp
    Contributor

    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.

  7. thesmithee commented on Nov 7, 2015

    @thesmithee

    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?

  8. cartermp commented on Nov 9, 2015

    @cartermp
    Contributor

    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.

  9. thesmithee commented on Nov 9, 2015

    @thesmithee

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

  10. BethMassi commented on Nov 10, 2015

    @BethMassi
    Contributor

    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.

  11. mairaw commented on Nov 10, 2015

    @mairaw
    Contributor

    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.

  12. cartermp commented on Nov 10, 2015

    @cartermp
    Contributor

    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?

  13. thesmithee commented on Nov 10, 2015

    @thesmithee

    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.

  14. BethMassi commented on Nov 10, 2015

    @BethMassi
    Contributor

    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.

  15. cartermp commented on Nov 10, 2015

    @cartermp
    Contributor

    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

  16. 3 remaining items

  17. stevehoag commented on Nov 19, 2015

    @stevehoag
    Contributor

    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//issues/52#issuecomment-157911157.

  18. thesmithee commented on Nov 19, 2015

    @thesmithee

    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.

  19. cartermp commented on Nov 19, 2015

    @cartermp
    Contributor

    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.

  20. BethMassi commented on Nov 19, 2015

    @BethMassi
    Contributor

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

  21. thesmithee commented on Nov 19, 2015

    @thesmithee

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

    I mean "ecosystem". Typo. :)

  22. cartermp commented on Nov 19, 2015

    @cartermp
    Contributor
  23. BethMassi commented on Nov 19, 2015

    @BethMassi
    Contributor
  24. BethMassi commented on Nov 19, 2015

    @BethMassi
    Contributor

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

  25. thesmithee commented on Nov 19, 2015

    @thesmithee

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

  26. BethMassi commented on Nov 19, 2015

    @BethMassi
    Contributor

    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.

  27. thesmithee commented on Nov 19, 2015

    @thesmithee

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

  28. SF-Alain commented on Mar 3, 2023

    @SF-Alain

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

  29. mairaw commented on Mar 5, 2023

    @mairaw
    Contributor
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

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions