Write the Context/Narrative

[JordanMartinez]

This is a WIP.

[chexxor]

I started to read the current state of this. I think it's really great! I wonder - should we use more citations or more specific citations here?

I proposed some changes in the following PR. Just some suggestions to tie the paragraphs together, I think.
#51

[JordanMartinez]

I wonder - should we use more citations or more specific citations here?

Yeah. I'm just writing out my initial go. I've been looking at the All Interpretations document throughout to help me.

I'll check that PR out.

[JordanMartinez]

Also, I'd like to explain my overall thought process behind this.

Purpose

To answer your question as though various people were all asking the same question and help them determine how to best respond to the current context.

Principles

Make it so people actually read it

We need to write this document in such a way that people will actually read it. (For example, see How to Write Technical Posts (so people will read them)

Thus, I'm trying to make things 'skimmable' by using:

• nested headers with clear names
• number lists
• bullet lists
• tables
• 4 instead of "four"
• small simple sentences
• small paragraphs

I tend to like to write really long sentences, so the 'simple sentences' part will be harder for me.

Cite our works in most sensible manner without being overwhelming.

We need to include citations to various things to show that we're not making these conclusions up, and so that others can check our research for its context and make their own conclusions if need be

I believe we can accomplish this like so:

What to cite	Where to include them	Why?	Example
Specific Links	Some sentences	desire to highlight important points (and refer to specific section when it does not have an anchor link)	How A is B? One might think C. However, it's really X (source, 3rd paragraph)
Sections in 'All Interpretations' file	Paragraphs or Sections in the document	desire to summarize main ideas in interpretations / give more context to conclusions	A is B, but sometimes C gets in the way. D is also a factor. (source)
This documentation repo	The end of the document	Provide full context of our analysis	All our research and analysis work appears in PureScript Documentation Discussion

Outcome

• learners know how to best learn in this situation
• doc writers know guidelines to follow, have a 'checklist' to ensure they have 'good' documentation in this regard, and have 'templates' they can use to quickly get started
• core contributors.... Well, I'm not sure what the outcome should be here
• users of PS... same as core contributors: what outcome should be here?

Brainstorm

1. explain common stuff to all audiences
2. explain specific stuff to each audience
3. explain our research methodology and conclusions by referring to this repo

Next actions

• Jordan: continue writing the structure of the document
• Alex: for people who want to see the 3rd brainstorm point above, write a document that explains how to navigate this repo as clearly as possible (likely just by referring to various parts in this repo)

How does that sound? What changes would you make to the above?

[JordanMartinez]

To address workflow issues, how does this procedure sound?

We can then do any final edits in this PR

[chexxor]

This point isn't addressed by looking at the ToC. I'll spend time in the next few days to understand this difference and find a way to resolve it.

[chexxor]

A related thing I noticed: The first thing that is discussed in this document is "What is Good Documentation?", from the ToC, but I expect to learn about the "State of PureScript Documentation", as that's the title of the document.

[chexxor]

The purpose of this step, from its ReadMe:

A "context" or "narrative" is a person or group of people's attempt at integrating their isolated interpretations of various sources into a coherent "story" that explains all the relevant pieces of the puzzle in a systematic way.

So, we have accumulated "interpretations of various sources" from a previous step, and it sounds like this step is to integrate those into a single "story". To explain the "explains all the relevant pieces" part, then: When putting a piece into this "story", it should be self-evident that it does indeed belong in the story.

[chexxor]

It's a little difficult to create a "story" when given no "grounding" or constraints, so let's say choose the grounding to be "How can we improve the PureScript documentation in 2019", as it was the original motivation question of this project.

1. How can we improve the PureScript documentation? This question is doesn't have a clear answer, so we need to break it down into smaller questions:
2. What should documentation look like?
3. How does current PureScript documentation compare?
4. Why is PureScript's documentation lacking in the places it is?
5. How should we improve these weak areas of documentation?

Judging purely from the current ToC, it's not clear where the "Addressing Audiences" section belongs in the above list of questions.

(I realize I've discussed the ToC issue with @JordanMartinez before, but this current ToC still bothers me, perhaps because I don't see how it's relevant to the title of the document and the overall goal of the project.)

[chexxor]

In #50 (comment), Jordan says:

Outcome

• learners know how to best learn in this situation
• doc writers know guidelines to follow, have a 'checklist' to ensure they have 'good' documentation in this regard, and have 'templates' they can use to quickly get started
• core contributors.... Well, I'm not sure what the outcome should be here
• users of PS... same as core contributors: what outcome should be here?

It looks like Jordan implicitly broke down the "How can we improve the PureScript documentation?" question into those four topics. This is different than how I broke down that question just now in my previous comment. I think this is a primary reason for the difference in ToCs we are preferring.

[chexxor]

I use the term documentation to refer to any written material that answers questions about a project. To me, the primary value of documentation is that I don't need to be in the rare state of having a person who is knowledgeable about the project and also available to answer my questions and also able to clearly communicate the answers to me. Core contributors and documentation writers both have questions about a project that need answering.

Regarding the ToC/structure of the document, when I was first trying to understand the structure of the document I think I viewed the "addressing various audiences" part as an essential part of the document. On my own, I couldn't think of a way to reasonably have that as a primary part of this document while keeping its scope/goal/content as it was, so I started to get creative with it. It seems now that I may have misunderstood that part's importance. If it's not an essential part of this document, then perhaps we can move it somewhere else? The following paragraph explains my thinking on this proposal.

I intended this document's authors and audience to be documentation managers, to be a unified understanding of the situation. Based on this document, then, documentation managers could define "outcomes" and clear steps towards them. Some guesses I have about our misunderstanding: 1) It seems you want this document's audience to be contributors and even consumers of PureScript's documentation, or perhaps 2) You intended to include some Outcomes and steps towards them in this narrative. I might disagree with having these two things as part of this document.

What do you think? Am I getting closer to the core of our misunderstanding?

In the meantime, I'll review this document again, in light of my new understanding of your original intentions (what I think were original).

[chexxor]

Ah, I forgot that we had talked about it maybe making sense for this document to contain desired outcomes. I'll have to find that past discussion.

Perhaps we just need to have a ToC header for that section which is more descriptive of it's relation to the other stuff in this document.

[JordanMartinez]

I use the term documentation to refer to any written material that answers questions about a project. To me, the primary value of documentation is that I don't need to be in the rare state of having a person who is knowledgeable about the project and also available to answer my questions and also able to clearly communicate the answers to me.

Ah... Then perhaps we're disagreeing about the 'scope' of the projects in question? I like your definition of documentation and I agree with it. However, I have not been including the PureScript language repository as a project that we should include when discussing PS' docs, mainly because most people who want to learn PureScript aren't going to immediately contribute to that.

Perhaps our disagreement lies in two aspects: using the same terms to refer to different meanings, having emphasis on different aspects of the work, and having different breadths of scopes.

For example, I intended the audience of this work to be all of the following--curious outsiders who are interested in the language and keeping updated about it, but who haven't started using it; new learners; people who already know and are familiar with it; and core contributors (primarily language developers, but people who contribute to build tools and whatnot as well), so they can stay in the loop of the conversation and add their input--as a way to explain "Here's where we are in things and why we are there (so we can have some parameters/guidelines to help us know what the problem is and how to fix it). Now that we know more about the problem, what can we do to fix it (answering Alex's original question)?"
However, my emphasis was largely on new learners in general (perhaps because I picked up that 'bias' when reading through our sources). I assumed we had a few goals in mind:

• improving the new learner onboarding experience
• improving Pursuit docs throughout the ecosystem
• explaining more FP ideas and best practices in general, so that people can actually be productive with the language

I did not include these goals:

• help people know how to contribute to the PureScript language
• help core contributors figure out whether and how to improve their administrative policies/procedures (something I'm realizing right now as I type this)

Some guesses I have about our misunderstanding: .... You intended to include some Outcomes and steps towards them in this narrative. I might disagree with having these two things as part of this document.

Originally, I did not want the Outcome parts included here. Over time, as I continued working on this document, Outcomes started to seep in as my mindset thought of ideas for solving various problems. After a while, I thought it might be best to include them here (via the Outcomes file link) since people would also be in similar mindsets and might come up with good ideas.

[chexxor]

A side-note: I think our misunderstanding of how to develop this document will serve as great reference when considering ways to prevent this from occurring in the future, because I imagine this problem is an essential problem of collaborative documentation. It seems important to define the primary terms used in the document and to clearly define the goal & audience and perhaps the non-goals and non-audience, and more items as they are discovered.

Regarding the audience of this document, I think we can certainly narrow the scope to only the "new learners" audience. However, I think it's important to acknowledge the existence of the other audiences and to explain why they are not explored. (I imagine they will be explored at a future time, perhaps by a different doc team.) I think this is important to do because when the non-goals are explicit, the boundary/scope of the project is more clear and serves as a "tangible boundary" to reference when reviewing a documentation contribution.

Here's a patch which nearly completely resolves my concerns with this document - #68 I will think about the "Addressing Various Audiences" section next.

Regarding the Outcomes exploration in this document - I think we can include that in this document. However, as they are right now I don't clearly read them as Outcomes. I'll consider the wording I would expect to see to read it as Outcomes.

[JordanMartinez]

Yeah, things were going well in terms of our collaboration up until this Context/Narrative part.

Ok, I'll wait to hear from you regarding the Outcomes stuff.

[JordanMartinez]

Due to my recent work in my learning repo (specifically, this comment), I think another goal should be to improve the testing libraries we use. It's hard to make the ecosystem more stable if library authors are wasting their time figuring out our testing environment.

[JordanMartinez]

@chexxor Referring to a comment that I replied to today, we can't remember where our old discussions are anymore 🤣

What can we do to fix that problem?

[chexxor]

@JordanMartinez I was also thinking of that problem. I was planning on searching my email for them, because Github sends me email notifications of comments in this project. I think those emails also link back to the original comment on the Github website. 🤷‍♂

[JordanMartinez]

@chexxor That's a good idea.