Refactoring the Guide

[theo-cox]

When I'm reading the guide, I want to an engaging route into the information that directly addresses my questions or perceptions.

Proposal of how we do this is outlined here, and involves merging the guide and claims page: https://docs.google.com/document/d/1woIRzvY6pdF43LQEFXHon1lUpIBe12Rj7WNZHXDdrnI/edit?usp=sharing

Note we should do this in Gdoc first, then convert to markdown and add to the site once the GDoc has been reviewed add signed off

Acceptance

• [ ] All content (e.g. all site pages such as notes ad concept pages) is arranged in the guide in a structured fashion

Tasks

Refactored guide draft (WIP) is here

• [x] Count the total number of pages on the site (probably via exploring the GitHub repo) to ensure none are missed All .md files in site/content are listed in this spreadsheet
• [x] Draft better economy section @catherinet1
• [x] draft better society section @EilidhRoss1
• [x] draft financial liberty section @catherinet1
• [x] draft public goods problems section @EilidhRoss1
• [x] draft innovation & progress section @catherinet1 ~~- [ ] draft creative destruction section @EilidhRoss1~~ got rid of this aspiration/merged with innovation and progress or other aspirations
• [x] draft intro to guide
• [x] draft foundational concepts section ✅ See aspirations doc
• [x] integrate rest of concepts and notes pages ✅ See aspirations doc
• [x] Categorise in spreadsheet definitional concepts by topic ✅ Fixed
• [x] update refactored guide with new pages ✅ as of 27/07/22 the guide is up to date
• [x] refactor claims pages (?) see analysis ✅ all problematic claims pages are fixed
• [x] Fix any notes pages needing fixed. See comments in the spreadsheet ✅Reviewed Eilidh's comments and fixed all. Minimal edits made and decided to leave 'todos' given open-source/wiki nature of site. Opened an issue to track issue with images not showing.
  ~~- [ ] Make glossary of concepts~~ WONTFIX. Decided not worth doing this
• [x] Putting this issue tree at the top https://coggle.it/diagram/Yh-L7j5DfRykGi7e/t/web3-what-is-the-evaluation-polarizing-way-as-possible and speaking to it in the intro e.g. the main claims made in the space are... [as a related aside, I'd also avoid repeating our boilerplate text too much in the intro, as per he first para currently] ✅ See aspirations doc
• [x] Writing up descriptions of each aspiration and claim as full text rather than bullet points. E.g. "This section covers the aspirations of web3 to improve...by...It contains the following claims..." and "This claim states that web3 will achieve X by doing Y" ✅ See aspirations doc
• [x] Adding short evaluations of the claims e.g. "On the basis of current evidence, this claim seems [plausible, implausible, false, true, unknowable] under X conditions for Y reasons" ✅ See aspirations doc
• [ ] Publish on site
  • [ ] Convert Google doc into Markdown: draft in hackMD (follow our style guide https://playbook.datopian.com/style-guide/markdown/ - and also note there is a plugin for google docs that auto converts to markdown and there are tools on the web to do this kind of conversion)
  • [ ] Transfer to guide/index page in repo and commit

[rufuspollock]

@theo-cox reviewed the doc and looks excellent.

Also may want to check out our original plan issue in #77 (and close in favour of this?) plus @olarubaj thoughts in #144

[theo-cox]

Great, thanks for the input @rufuspollock. Will close #77 as I think it would require a bit of extra content creation vs this refactoring. Think the thoughts in #144 are largely addressed by this, also, which is good!

[catherinet1]

@EilidhRoss1 link to spreadsheet with all site pages listed is above

[catherinet1]

@EilidhRoss1 @theo-cox I updated the issue with tasks completed and next actions

[EilidhRoss1]

All pages in the site are now organized into the aspirations doc - except those concepts which don't contribute anything to any claim and which will go in an organized glossary section. All concepts have been categorized as economics, finance, tech, ideology, or social phenomena (open to different wording, esp on the social phenomena one). All unassociated concepts have been marked as such. Only other site pages which don't feature are some notes pages which as is (IMO) don't contribute anything or need quite a bit of editing before they should be in the refactored guide (all such notes pages have comments in the spreadsheet). TODO (as updated in issue): rewrite those claims which need rewritten (spreadsheet outlining which ones need fixed found here), fix any notes pages worth fixing and make the glossary.

[theo-cox]

Amazing work @EilidhRoss1 and @catherinet1 ! A handful of things that came out of the Labs meeting yesterday [which I'll put in the issue above]:

• Putting this issue tree at the top https://coggle.it/diagram/Yh-L7j5DfRykGi7e/t/web3-what-is-the-evaluation-polarizing-way-as-possible and speaking to it in the intro e.g. the main claims made in the space are... [as a related aside, I'd also avoid repeating our boilerplate text too much in the intro, as per he first para currently]

• Writing up descriptions of each aspiration and claim as full text rather than bullet points. E.g. "This section covers the aspirations of web3 to improve...by...It contains the following claims..." and "This claim states that web3 will achieve X by doing Y"

• Adding short evaluations of the claims e.g. "On the basis of current evidence, this claim seems [plausible, implausible, false, true, unknowable] under X conditions for Y reasons"

@rufuspollock one final thing which we didn't get to chat through yesterday was some of the claims pages risk reading as overly inflammatory and biased, undermining our plausibility as a sensemaking resource. It's been suggested that we alter these, and it would be good to get your input here.

[EilidhRoss1]

@theo-cox I've done these tasks (of course happy to make further edits) and have updated the issue

[rufuspollock]

@rufuspollock one final thing which we didn't get to chat through yesterday was some of the claims pages risk reading as overly inflammatory and biased, undermining our plausibility as a sensemaking resource. It's been suggested that we alter these, and it would be good to get your input here.

I would be happy to see editing in line with this.

[theo-cox]

Great! @catherinet1 and @EilidhRoss1 could you then action the changes you've flagged as necessary? We can then push the guide live! For ones about references etc Zotero should have lots of good stuff, but if you're unsure of anything then please do let me know. We can also discuss issues in Labs tactical next Tuesday

[EilidhRoss1]

All claims pages have been appropriately fixed. The guide is up to date will all pages. I think we're moving onto the next stage which would be getting feedback from Theo and Rufus and then putting the guide into markdown and getting it up on the site!

[theo-cox]

Having had a brief skim this looks great @EilidhRoss1 well done! My one comment would be its probably worth having a small sub-heading to separate the evaluation from the description. Other than that I'd say let's get it up asap!

[catherinet1]

Updated Fix notes pages task.

[catherinet1]

Having had a brief skim this looks great @EilidhRoss1 well done! My one comment would be its probably worth having a small sub-heading to separate the evaluation from the description. Other than that I'd say let's get it up asap!

Added sub-heading to separate evaluation from description

[theo-cox]

Great thanks @catherinet1! Really excited to see the finished product up on the site. You and @EilidhRoss1 have done an excellent job

[rufuspollock]

FIXED. New guide is up at https://web3.lifeitself.us/guide.

Going to mark this as fixed as acceptance is done and for follow up see parent epic #193