search

chexxor / purescript-documentation-discussion

A place to organize the planning of improvements to the PureScript documentation.
7 stars 0 forks source link

Clarify "Learner's Phase" table #70

Open chexxor opened 5 years ago

chexxor commented 5 years ago

I, and perhaps @JordanMartinez also, feel that the "Learner's Phase" table in the Context/Narrative document is a little wrong in its "abstraction" of the issue. What exactly is "off" about it isn't clear, so the resolution is also not clear.

Perhaps the problem is simply that I am wanting it to be something that it isn't trying to be. For example, perhaps I want it to describe the various audiences the documentation needs to address, whereas the table is simply trying to describe the various types of documentation and invents a persona to which it is most valuable.

Motivated by this thread: https://github.com/chexxor/purescript-documentation-discussion/pull/50/files#r277185921

chexxor commented 5 years ago

I don't see the exact phases in the "Learner's Phase" table in https://www.divio.com/blog/documentation/, so perhaps it's an extrapolation by @JordanMartinez. If that's the case, we have more flexibility when clarifying it.

JordanMartinez commented 5 years ago

The X-Y graph I was referring to is the last image in that post. The top-left corner reads "Tutorials<br>Learning Oriented". I would like to copy-and-paste that image into this repo, but that's too much of a copyright infringement in my mind.

Also, due to the influence of "Teach, don't tell," our table added a fifth type, which takes one of their types and breaks it down into two types.

JordanMartinez commented 5 years ago

When I initially wrote that part, I thought about re-creating their image using HTML tables but decided against it for two reasons: