Skip to main content
Commonmark migration
Source Link

##Two options to improve browse-ability.###

Two options to improve browse-ability.

Option 1: Have a (logically ordered) Table of Contents on each topic.

###Option 1: Have a (logically ordered) Table of Contents on each topic. TheThe site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach ThisThis is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

##Two options to improve browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

Two options to improve browse-ability.

Option 1: Have a (logically ordered) Table of Contents on each topic.

The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach

This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

deleted 360 characters in body
Source Link
aaronsteers
  • 2.6k
  • 10
  • 6

##Two options to improve browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

** To further emphasize why this is needed, time will show that more advanced topics are likely to get more votes versus the simple ones, with the most natural order being a reverse-ordering of most-complex to least-complex topics. (Meaning: A beginner reading a random topic would be better off reading the docs from bottom up. Is that what we really want?)

##Two options to improve browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

** To further emphasize why this is needed, time will show that more advanced topics are likely to get more votes versus the simple ones, with the most natural order being a reverse-ordering of most-complex to least-complex topics. (Meaning: A beginner reading a random topic would be better off reading the docs from bottom up. Is that what we really want?)

##Two options to improve browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

deleted 6 characters in body
Source Link
aaronsteers
  • 2.6k
  • 10
  • 6

##I agree, and here are two##Two options to fix itimprove browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

** To further emphasize why this is needed, time will show that more advanced topics are likely to get more votes versus the simple ones, with the most natural order being a reverse-ordering of most-complex to least-complex topics. (Meaning: A beginner reading a random topic would be better off reading the docs from bottom up. Is that what we really want?)

##I agree, and here are two options to fix it.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

** To further emphasize why this is needed, time will show that more advanced topics are likely to get more votes versus the simple ones, with the most natural order being a reverse-ordering of most-complex to least-complex topics. (Meaning: A beginner reading a random topic would be better off reading the docs from bottom up. Is that what we really want?)

##Two options to improve browse-ability.###

###Option 1: Have a (logically ordered) Table of Contents on each topic. The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

###Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

** To further emphasize why this is needed, time will show that more advanced topics are likely to get more votes versus the simple ones, with the most natural order being a reverse-ordering of most-complex to least-complex topics. (Meaning: A beginner reading a random topic would be better off reading the docs from bottom up. Is that what we really want?)

added 34 characters in body
Source Link
aaronsteers
  • 2.6k
  • 10
  • 6
Loading
Source Link
aaronsteers
  • 2.6k
  • 10
  • 6
Loading