Context or Narrative planning

[chexxor]

While currently not finished with the first stage yet, it doesn't hurt to start discussions of the next stage, "Context or Narrative", particularly how it relates to the previous stage, "Sources and Interpretation".

The goals of this second stage is clearly stated in the "02-Context-or-Narrative.md" file. The goal that will be most relevant to the previous stage is "to define the purposes that need to be fulfilled". So, when it comes time to enter this second stage, we can make one/multiple work item(s) for that. These work items will consist of developing goals for this project educated by the facts discovered in the previous stage.

So, I think a good process for doing that is:

• organize the discovered facts into some common types
• summarize the facts in each type
• develop one/multiple goals educated by these summaries
• fulfill the goals defined in the "Context or Narrative" file

With this process, we can collaborate by having one person manage each type of fact through the rest of the process.

[JordanMartinez]

With this process, we can collaborate by having one person manage each type of fact through the rest of the process.

Sounds good to me. It sounds like we'll be organizing the data by type/theme/pattern/subject and then provide a coherent explanation for that particular topic.

Pehaps after we finish the 'sources and interpretation' phase, we can determine what are the various topics to consider?

[chexxor]

Perhaps after we finish the 'sources and interpretation' phase, we can determine what are the various topics to consider?

In https://github.com/chexxor/purescript-documentation-discussion/issues/21 I proposed some goals of the project. I would guess it's a bit backwards to do it to propose goals, which is a middle-stage, before/while examining sources, but it seems important to know the goal when selecting sources.

I realize now that the "Project Goal" in the README exists, but it is less specific or concrete than the goals I proposed in the issue linked just above. Do we need goals which are more specific like this? If so, should we collect a list of goals in the project root directory?

[JordanMartinez]

I'll respond to this tomorrow so I can get more sleep tonight and give a better response than I can give in 2 minutes :-)

[JordanMartinez]

I'm assuming you're referring to this comment when you mention proposing some goals of the project.

I don't think that's necessarily 'backwards' as those goals are better informed by the work we've done thus far and other ideas we've had since the creation of this project.

Do we need goals which are more specific like this? If so, should we collect a list of goals in the project root directory?

Eventually, but we're not at that phase yet. That's what this folder and its outcome files are for. Once we've done more data analysis and figured out "what is even going on," we'll have a better idea of what the project's ultimate goals will be. However, we're currently pursuing the goal of becoming informed.

[JordanMartinez]

So, continuing the discussion here...

I think our approach for writing the Context/narrative should work like so:

1. Copy all interpretations currently in "Done" folder into a new file "all interpretations.md" (When Alex finishes a source in his folder, we can include it in this new file). When copying over a file's interpretations, include the source's slug_name in brackets following the interpretation.
2. Organize these interpretations by topic/theme that begin to emerge after a while (e.g. What is 'good' documentation? What are relevant factors in regard to this effort? etc.), then organize the sources within a topic by date (top entries are older, bottom entries are newer)
3. Determine how the sections should likely be ordered
4. Write a summary for each section based on that interpretations included there
5. Write some "concluding questions" that the community should ponder on their own or discuss.
6. Edit final work to insure it's logical flow is sensible and the tone is calm, understanding, and confident
7. Once we agree on what it says, post the work on Discourse with a link referring to this repo.
8. Notify people in the PS community via Reddit, Slack, and Twitter

Edit:

• added the 'slug name in brackets' idea
• added the 'organize by source date after organizing by topic' idea

[JordanMartinez]

I'm going to edit the above procedures. I think a source should an interpretation should also include the source's slug name, so that people can find the full context of some interpretation as some sources are older and not as recent, so they shouldn't bear as much weight.

[JordanMartinez]

Just an update. I've pushed All-Interpretations.md to master.

[JordanMartinez]

Once we get the rest of the sources in your folder done, we can overview the entire work in a PR and then start figuring out how to cut down on it or summarize things.

[JordanMartinez]

Ok, so I've copied over all of the interpretations from the sources that were in the 'done' folder (except for the 'what nobody tells you about documentation') into the 'all intepretations.md' file.

I have not yet integrated them into the sections I already have in that file or new ones that will need to arise due to them.

[JordanMartinez]

Also, did you want to review 'Infrastructure analysis.md'? I wasn't sure whether to put it in the 'for alex' folder or not.

[chexxor]

It can sit where it is - I'll look though it today and decide where I can make some improvements. I fixed a few typos just now.

[chexxor]

@JordanMartinez I added a table of contents to the Infrastructure Analysis file and re-organized it by infrastructure project. Feel free to revert some of my commits if you disagree with those changes.

I wonder if that document should be renamed to "User-Experience-Analysis" or similar. I associate "infrastructure" with hardware stuff, but while some of the items in that document are indeed infrastructure (purs docs and Pursuit), others are simply projects which new users are likely to want to use, like pre-existing documentation projects.

[JordanMartinez]

It can sit where it is - I'll look though it today and decide where I can make some improvements.

Thanks!

I fixed a few typos just now.

All your typo-fixing has made me realize just how many typos I accidentally type. I guess Microsoft Word has been fixing all of them automatically for me without me realizing it.

I added a table of contents to the Infrastructure Analysis file and re-organized it by infrastructure project. Feel free to revert some of my commits if you disagree with those changes.

I think they are fine. Our main priority is getting the final summary written.

I wonder if that document should be renamed to "User-Experience-Analysis" or similar. I associate "infrastructure" with hardware stuff, but while some of the items in that document are indeed infrastructure (purs docs and Pursuit), others are simply projects which new users are likely to want to use, like pre-existing documentation projects.

Mm... I guess this file covers more than just infrastructure (e.g. other learning resources). Maybe it should be split up into more files?

• infrastructure & Pursuit Overview
• learning resources

[JordanMartinez]

Ok, so I've split up that infrastructure analysis file into two.

I've also finished categorizing the remaining sources and cleaning up the 'all interpretations' file itself to make it easier to skim via the ToC tool you used (nice find, btw).

So, here's what we have left:

• [x] finish the review of the mvi-architecture
• figure out how to integrate these files into the 'all interpretations' file:
  • [x] the 'infrastructure analysis file
  • [x] the learning resources file
  • [x] the what nobody tells you about documetation post
• [ ] then we can start writing the Context/Narrative using the All interpretations file

[JordanMartinez]

figure out how to integrate these files into the 'all interpretations' file:

• the what nobody tells you about documetation post

Maybe we should just include a link to that post in the 'all interpretations' file's corresponding section?

[JordanMartinez]

I've finished up most of the work in my learning repo regarding the Table of Contents project. I'd like to focus all my efforts in the upcoming week on writing the context/narrative part.

[JordanMartinez]

Turns out the ToC project took a bit longer than expected. The good news is that I've largely finished the program now. I just need to determine how to best integrate it into my workflow on that project.

So, I'll be getting to this again either today or tomorrow.

[JordanMartinez]

See #50 (WIP)