Howdju · carlgieringer · Jan 8, 2024 · Jan 7, 2024 · Jan 7, 2024 · Jan 8, 2024
diff --git a/howdju-docs/README.md b/howdju-docs/README.md
@@ -18,11 +18,13 @@ yarn run build-and-start
 
 ## Deployment
 
+Build the docs locally:
+
 ```sh
 yarn run build-and-export
 ```
 
-Upload contents of `out` folder to s3://docs.howdju.com.
+Upload contents of `out` folder to s3://docs.howdju.com:
 
 ```sh
 aws-vault exec user@howdju -- aws s3 sync out s3://docs.howdju.com

diff --git a/howdju-docs/not-found.html b/howdju-docs/not-found.html
@@ -1,4 +1,5 @@
 <html><script>
+  // See https://stackoverflow.com/a/77070757
   var url = new URL(window.location.href);
   if (url.pathname.endsWith('.html')) {
     // If the path already ends with html, there isn't another path we can try.

diff --git a/howdju-docs/pages/_meta.json b/howdju-docs/pages/_meta.json
@@ -1,5 +1,6 @@
 {
   "index": "Home",
+  "introduction": "",
   "features": "",
   "concepts": "",
   "community": {

diff --git a/howdju-docs/pages/features.mdx b/howdju-docs/pages/features.mdx
@@ -4,11 +4,12 @@
 
   - Browser extension
   - Mobile app
-  - Text fragment links
+  - Text fragment link support
 
 - Convenient viewing of evidence in-context
 
-  The same three tools enable quickly viewing a MediaExcerpt in situ.
+  The same three tools enable quickly viewing a
+  [MediaExcerpt](/concepts/media-excerpts) in situ.
 
 - Consolidate equivalent entities and connect related ones
 
@@ -18,37 +19,220 @@
 - Sort content
 
   - Global voting
+  - With plans to cluster users and rank content according to representativeness
+    across clusters
 
 - Track speaker reputation/credibility
 
 ## Use cases
 
 - Bookmark meaning
 
-  When you create a MediaExcerpt, you do more than bookmark a URL. You save a quotation, a URL, and
-  optionally a speaker and a source.
+  When you create a [MediaExcerpt](/concepts/media-excerpts), you do more than
+  bookmark a URL. You save a quotation, a URL, and optionally a speaker and a
+  source.
 
-  If you create an Appearance or Justification using the MediaExcerpt, you are now saving the
-  meaning of what was said.
+  If you create an Appearance or [Justification](/concepts/justifications) using
+  the [MediaExcerpt](/concepts/media-excerpts), you are now saving the meaning
+  of what was said.
 
 - Critique sources
 
-  Create Appearances in a Source and then add Justifications to the Propositions to decide whether
-  the Source's claims are credible.
+  Create [Appearances](/concepts/appearances) in a [Source](/concepts/sources)
+  and then add [Justification](/concepts/justifications) to the
+  [Proposition](/concepts/propositions) to decide whether the Source's claims
+  are credible.
 
-- Research a Proposition
+- Summarize sources
 
-  Create a proposition and then add Justifications to it from various sources to decide whether it's
-  true, false, or maybe unknown.
+  Create [Appearances](/concepts/appearances) in a [Source](/concepts/sources)
+  and then use the Appearances' [Propositions](/concepts/propositions) to
+  [Justify](/concepts/justifications) Propositions that summarize the thinking
+  or arguments in sections of the source. If the source explicitly states or
+  implies the conclusions, you can mark these summaries with Appearances of the
+  conclusions.
 
-## Privacy
+- Analyze argument
 
-Howdju shows the creator for most entities. Therefore most content users create on Howdju is
-attributable to them. Votes are generally not attributable to their creators. The exceptions to this
-are:
+  Create a proposition and then add [Justification](/concepts/justifications) to
+  it from various sources to decide whether it's true, false, or maybe unknown.
 
-- When there is just one vote on an entity, Howdju currently does not obfuscate the vote count and
-  so it could be inferred to the creator of the content.
-- Howdju is exploring Fact Checks which use a User's vote on a MediaExcerpt locator to determine
-  inclusion in the Fact Check. This approach implicitly exposes the users vote on the locator to
-  other users.
+## Comparison to well-known platforms
+
+The following sections compare Howdju to well known platforms that provide a
+crowdsourced fact checking role even though they were not initially or
+explicitly designed to do so.
+
+### Wikipedia
+
+Howdju is like Wikipedia in that it focuses on facts and evidence. Howdju is
+more like reddit or Stackoverflow in terms of the process it uses to accept and
+present facts and evidence.
+
+Wikipedia pages have a single representation at any time that is the result of a
+highly moderated consensus. Some pages are even locked, preventing ordinary
+users from making any contributions.
+
+Howdju users do not require consensus to create content or to present it.
+instead consensus on Howdju contributes to the relative ranking of content.
+Users can create a new Proposition at any time, can add their own justifications
+to other's Proposoitions, can add Appearances to other's Propositions, etc.
+Users can share views of their own content and other users can contribute to
+that content directly.
+
+Compare that with Wikipedia where, although you can share a link to a previous
+version of a page you wrote, if your contribution was reverted by a moderator,
+no one can contribute on top of your content since it will contain the same
+content that the moderator originally reverted, and they will revert it again.
+
+### Reddit
+
+Howdju is inspired by Reddit's threading model, but Howdju does not accept free
+form text, links, and media. Howdju content is focused on claims and evidence,
+and so has a more restrictive data model. Howdju also splits threads into two
+sides: one for Pro justifications and one for Con justifications.
+
+Reddit's distributed totalitarian moderation model was initially highly
+successful, but has been deteriorating in recent years. Subreddit moderators now
+ban users who express even mildly contrarian views, creating information silos /
+"filter bubbles".
+
+### Twitter
+
+Similar to Reddit, Twitter accepts free form text, link, and media and has no
+domain primitives for claim or evidence.
+
+Twitter's Community Notes (formerly Birdwatch) provide a crowdsourced fact
+checking layer on top of Twitter's content. Community notes have two major
+drawbacks:
+
+1. Only a single Community Note can appear on a Tweet.
+
+   This limitation prevents alternative or complementary Notes from appearing on
+   the same Tweet. This limitation means that a single Community Note must try
+   to encompass all of the most important feedback on a Tweet, which is
+   especially challenging since Notes have the same length limitations as Tweets
+   (at least for non-premium subscribers.)
+
+2. It is not possible to respond to a Community Note.
+
+   This limitation means that if a Community Note is approved, no important
+   rebuttal or contradicting context can be added to note. This also means that
+   there is limited opportunity to incrementally improve a Community Note
+   through feedback.
+
+### Quora
+
+Quora questions and answers are closer to Howdju's Propositions and
+Justifications than Wikipedia pages: they allow multiple concurrent alternative
+responses to a question. But the Q&A data model is inferior to Propositions and
+Justifications for consolidating similar claims. Quora has no special domain
+model for evidence or for factchecking sources.
+
+### Stackoverflow
+
+Stackoverflow has a simple structured domain model and very strong documentation
+and community norms around acceptable content. Its gamification contributes to
+healthy participation with minimal detraction, and its privilege-based
+moderation and elected moderators are effective. Its meta community provides a
+mostly productive way for users to communicate about content and moderation.
+
+Stackoverflow relies upon aggressive manual moderation to remove duplicate
+content and does not intentionally tolerate similar questions that differ based
+on subtle nuanced wording differences.
+
+Stackoverflow (and the more generic Stackexchange technology) has no features
+geared directly to facts and evidence. There is a Stackexchange dedicated to
+critiquing claims
+([skeptic.stackexchange.com](https://skeptics.stackexchange.com)), but it has
+very strict rules for its answers, forbidding answers that synthesize sources or
+perform novel mathematical calculations. E.g. see [this
+answer](https://skeptics.meta.stackexchange.com/a/2925/47976) and [this
+answer](https://skeptics.meta.stackexchange.com/a/2930/47976).
+
+The problem with forbidding these types of answers is that sometimes those
+answers are what people are thinking or alluding to in their communications
+without coming out and specifying them. Since people frequently form beliefs
+based on 'common sense' and 'mental mathematical estimation', the skeptics
+stackexchange does its community a disservice by forbidding these types of
+answers.
+
+The problem, however, may not be the community's, but the tool's: Stackexchange
+only allows two levels of threading, and the second level is inferior to the
+first: Questions, Answers, and Comments. This limitation means that an answer
+based on invalid assumptions or reasoning is only open to critique through the
+comments, which are not sorted by vote and offer a poorer UX compared to
+Answers.
+
+Howdju's assumption is that it is better for people to share their reasoning
+explicitly, even if it is invalid, because then it is amenable to critique.
+Howdju's recursive domain model (Propositions are the targets of Justifications,
+which contain Propositions, which can be the targets of more Justifications,
+etc.) allows critique of such content.
+
+### Lobste.rs
+
+While perhaps not as well known as HackerNews, I admire Lobste.rs transparent
+moderation history and its invite structure.
+
+## Comparisons to similar projects
+
+The following sections compare Howdju to other crowdsourced argument mapping or
+fact checking projects.
+
+### Kialo
+
+* Cannot reuse claims
+* Limited evidence handling
+
+### Two dimensional maps
+
+Examples:
+
+* ponder.wiki
+* debatemap.app
+
+Two dimensional maps are useful for providing users quick visual context for a
+larger argument. They work best for closed participant argument mapping because
+the branching factor is relatively low and the relevance of the content to each
+participant is high.
+
+An open participation platform must handle an influx of new inexperienced users
+who may duplicate content or create low quality content. One mandatory response
+to this is education of community norms and moderation. But moderation doesn't
+scale well, and it takes time for users to internalize community norms.
+
+Howdju's two column approach provides a natural experience to exploring the
+arguments for and against a claim. As users explore lower ranked items in one
+column, the other can remain in place with the top-ranked content.
+
+An influx of new content will be ranked below existing quality content, but also
+immediately acessible to users to rank via infinite scrolling through the
+columns. This helps ensure that new content is crowd moderated.
+
+### Rating claims directly
+
+Some tools allow users to explicitly rate claims' truthfulness. This approach
+allows users to engage in expressive voting, where they vote for something
+because they already believe it rather than because they have found a justified
+reason for believing it.
+
+Howdju instead asks users to vote on the Justifications of Propositions. While
+no system that scores a value based on user input is immune to manipulation,
+this design encourages users both to focus on why they believe something rather
+than what they already believe, forces them to expend the effort to add (or at
+least find) a justification if they want to support a Proposition, and it helps
+users who want to argue against the proposition to understand what the best
+arguments are of those who believe in the Proposition.
+
+## Visibility
+
+Howdju shows the creator for most entities. Therefore most content users create
+on Howdju is attributable to them. Votes are generally not attributable to their
+creators. The exceptions to this are:
+
+- When there is just one vote on an entity, Howdju currently does not obfuscate
+  the vote count and so it could be inferred to the creator of the content.
+- Howdju is exploring Fact Checks which use a User's vote on a MediaExcerpt
+  locator to determine inclusion in the Fact Check. This approach implicitly
+  exposes the users vote on the locator to other users.
diff --git a/howdju-docs/pages/introduction.mdx b/howdju-docs/pages/introduction.mdx
@@ -0,0 +1,62 @@
+# Introduction
+
+If you have ever fact-checked a claim, you know how time-consuming it is. The
+steps include:
+
+- Articulating the claim you believe the speaker to be making based upon both
+  the literal phrasing and context.
+- Considering alternative articulations:
+  - Charitable alternatives, that you expect to be more true and might be:
+    - what the author meant
+    - what the author might agree to if presented with criticism
+    - what others might interpret the speech to mean, even if the author
+      disagrees
+  - Uncharitable alternatives that don't represent the speaker's intent, but
+    that others may incorrectly attribute to the speech.
+- Depending on whether a claim is a statement of fact or a conclusion drawn from
+  an explicit or implied argument, decomposing a claim into other claims that
+  form an argument for the conclusion.
+- For every claim resulting from this process, searching for evidence weighing
+  on the truth of the claim.
+- Finally synthesizing the evidence and arguments into a judgment on the
+  original claim and the most important alternatives.
+
+Whew! So now you have an informed personal conclusion about the speaker's claim.
+What do you do with it?
+
+## What next?
+
+If you embarked on the fact check as part of a conversation, you might report
+back your findings to your friends or colleagues. If you are someone with an
+active social media presence, you might broadcast your results, and some of your
+followers might try to make substantive contributions in the comments. Or if
+neither of those things apply, you might not do anything other than hope to
+remember your conclusions if it becomes relevant again.
+
+But can we do better? I think we can.
+
+## How Howdju helps
+
+Howdju is a prototype of a platform for crowdsourcing and sharing fact checks.
+It lets you store and share your fact checking analysis, deduplicating the
+effort required to fact check claims. It allows others to discover, evaluate,
+and contribute to your analysis.
+
+Howdju users can:
+
+* Share their fact check in a structured way online so that their friends or
+  colleagues can view, respond, and contribute to their fact checks.
+* Get specific structured feedback on the validity of your fact check from wide
+  audiences.
+* Record personal research so that you can find and refer to it later.
+
+But that's not all!
+
+## A community of truth seekers
+
+In addition to sharing their own fact checks, Howdju users benefit when other
+users share their fact checks:
+
+* In context highlighting of debated claims.
+* Searchable database of claims and justifications.
+* Notifications for fact check activity of users you follow.