big docs revision

templates/docs.html

@@ -16,7 +16,7 @@
 </div>
 
 <p>
-Bridgy Fed turns your web site into its own <a href="https://en.wikipedia.org/wiki/Fediverse">fediverse</a> account, visible in <a href="https://joinmastodon.org/">Mastodon</a> and beyond. You can post, reply, like, repost, and follow fediverse accounts by posting on your site with <a href="https://microformats.org/wiki/microformats2">microformats2</a> and sending <a href="http://www.webmention.org/">webmentions</a>. Bridgy Fed translates those posts to fediverse protocols like <a href="https://activitypub.rocks/">ActivityPub</a> and <a href="https://en.wikipedia.org/wiki/OStatus">OStatus</a>, and sends fediverse interactions back to your site as webmentions.
+Bridgy Fed turns your web site into its own <a href="https://en.wikipedia.org/wiki/Fediverse">fediverse</a> account, visible in <a href="https://joinmastodon.org/">Mastodon</a> and beyond. You can post, reply, like, repost, and follow fediverse accounts by posting on your site with <a href="https://microformats.org/wiki/microformats2">microformats2</a> and sending <a href="https://webmention.net/">webmentions</a>. Bridgy Fed translates those posts to fediverse protocols like <a href="https://activitypub.rocks/">ActivityPub</a> and <a href="https://en.wikipedia.org/wiki/OStatus">OStatus</a>, and sends fediverse interactions back to your site as webmentions.
 </p>
 
 <p>
@@ -33,16 +33,19 @@ Bridgy Fed takes some technical know-how to set up, and there are simpler (but l
 <p><em>Setup</em></p>
 <li><a href="#setup">How do I set it up?</a></li>
 <li><a href="#profile">How do I set up my profile?</a></li>
+<li><a href="#user-page">Where's my user page and dashboard?</a></li>
 <!-- <li><a href="#sites">Which sites are supported?</a></li> -->
 
 <br>
 <p><em>Usage</em></p>
-<li><a href="#use">How do I use it?</a></li>
+<li><a href="#how-post">How do I post to the fediverse?</a></li>
+<li><a href="#which-posts">Which of my posts will show up in the fediverse?</a></li>
 <li><a href="#reply">How do I reply to a fediverse post?</a></li>
 <li><a href="#like">How do I favorite (aka like) or boost (aka repost) a fediverse post?</a></li>
 <li><a href="#follow">How do I follow someone?</a></li>
 <li><a href="#image">How do I include an image in a post?</a></li>
 <li><a href="#fragment">Can I publish just one part of a page?</a></li>
+<li><a href="#backfeed">How do fediverse replies, likes, and other interactions show up on my site?</a></li>
 <li><a href="#read">How do I read my fediverse timeline/feed?</a></li>
 <li><a href="#discovery">How can people on the fediverse find me?</a></li>
 <li><a href="#troubleshooting">I tried it, and it didn't work!</a></li>
@@ -119,7 +122,7 @@ https://en.support.wordpress.com/site-redirect/
 
 </ul>
 
-<li>Add <a href="http://www.webmention.org/">webmention</a> support to your site. This is strongly recommended, but technically optional. You don't have to automate the webmentions to Bridgy Fed to federate your posts, and you don't have to accept the inbound webmentions that Bridgy Fed sends, but you'll have a much better experience if you do. <a href="https://indieweb.org/webmention#Publishing_Software">Check out the IndieWeb wiki</a> for instructions for your web server.</li>
+<li>Add <a href="https://webmention.net/">webmention</a> support to your site. This is strongly recommended, but technically optional. You don't have to automate the webmentions to Bridgy Fed to federate your posts, and you don't have to accept the inbound webmentions that Bridgy Fed sends, but you'll have a much better experience if you do. <a href="https://indieweb.org/webmention#Publishing_Software">Check out the IndieWeb wiki</a> for instructions for your web server.</li>
 </ol>
 </li>
 
@@ -143,7 +146,6 @@ Your site's fediverse profile comes from the <a href="https://microformats.org/w
 </pre>
 </p>
 
-
 <p>By default, your fediverse address will be <code>@yourdomain.com@yourdomain.com</code>. Many services (eg Mastodon) default to only showing the username, so this generally shows up as just <code>@yourdomain.com</code> in posts, and the full address appears on hover.</p>
 
 <p>We recommend this for simplicity and predictability, for everyone else as well as you, but if you want a different username, you can set it by adding an <code>acct:</code> <a href="https://microformats.org/wiki/rel-me">u-url</a> link inside your h-card with <code>username@yourdomain.com</code>, eg:
@@ -153,6 +155,13 @@ Your site's fediverse profile comes from the <a href="https://microformats.org/w
 </pre>
 </li>
 
+<li id="user-page" class="question">Where's my user page and dashboard?</li>
+<li class="answer">
+<p>
+<a href="/web-site">Enter your domain here</a> to see your user page. It shows your site's current status, recent interactions, remote follow UI, and links to your timeline feeds in various formats.
+</p>
+</li>
+
 <!-- <li id="sites" class="question">Which sites are supported?</li> -->
 <!-- <li class="answer"> -->
 <!-- <p> -->
@@ -182,11 +191,10 @@ Your site's fediverse profile comes from the <a href="https://microformats.org/w
 <br>
 <h3 id="usage">Usage</h3>
 
-<li id="use" class="question">How do I use it?</li>
+<li id="how-post" class="question">How do I post to the fediverse?</li>
 <li class="answer">
 <p>
-Create an IndieWeb <a href="https://indieweb.org/post">post</a>, <a href="https://indieweb.org/like">like</a>, <a href="https://indieweb.org/repost">repost</a>, <a href="https://indieweb.org/reply">reply</a>, or <a href="https://indieweb.org/follow">follow</a> as usual, and include a link to <code><a href="https://fed.brid.gy/">https://fed.brid.gy/</a></code> in that post. It can be empty if you want. Your web server should then <a href="#setup">send Bridgy Fed a webmention</a>, which it will translate and forward into the fediverse. Alternatively, <a href="https://indieweb.org/Webmention#Manual_Webmentions">you can send the webmention manually.</a> For example:
-</p>
+Create a <a href="https://indieweb.org/post">post</a> with the <a href="https://microformats.org/wiki/h-entry"><code>h-entry</code> microformat</a> on your web site. Many web servers include this or compatible microformats automatically. The post can be a <a href="https://indieweb.org/note#How_to">note</a>, <a href="https://indieweb.org/article">article</a>, <a href="https://indieweb.org/like">like</a>, <a href="https://indieweb.org/repost">repost</a>, <a href="https://indieweb.org/reply">reply</a>, or <a href="https://indieweb.org/follow">follow</a>. For example:
 
 <pre>&lt;div class="<span class='keyword'>h-entry</span>"&gt;
   Regarding &lt;a class="<span class='keyword'>u-in-reply-to</span>" href="<a href='https://mastodon.technology/@snarfed/3194674'>https://mastodon.technology/@snarfed/3194674</a>"&gt;this post&lt;/a&gt;:
@@ -194,16 +202,18 @@ Create an IndieWeb <a href="https://indieweb.org/post">post</a>, <a href="https:
   &lt;a href="<a href='https://fed.brid.gy/'>https://fed.brid.gy/</a>"&gt;&lt;/a&gt;
 &lt;/div&gt;
 </pre>
-
-<p>Basic HTML formatting like links, lists, bold, and italics are often preserved and visible in the fediverse, but specifics vary from site to site.
 </p>
 
-<p>
-To receive likes, reposts, replies, @-mentions, and follows from the fediverse, just make sure your site accepts webmentions! Bridgy Fed translates those interactions and sends them to your site as webmentions. The source URL will usually be a proxy page on <code>fed.brid.gy</code>. For best results, <a href="https://brid.gy/about#appspot">make sure your webmention handler detects and handles <code>u-url</code> links</a>.
+<p>Basic HTML formatting like links, bold, and italics are generally preserved and visible in the fediverse, but specifics vary from site to site.
 </p>
 
-<p>
-You can see your recent interactions by <a href="/web-site">entering your domain here</a>.
+<p>Then, include a link (optionally blank) to <code><a href="https://fed.brid.gy/">https://fed.brid.gy/</a></code> in that post and <a href="#setup">send Bridgy Fed a webmention</a>. That webmention will trigger Bridgy Fed to forward your post into the fediverse. Your web server may send the webmention automatically if it supports them, or <a href="https://indieweb.org/Webmention#Manual_Webmentions">you can send it manually.</a>
+</p>
+</li>
+
+<li id="which-posts" class="question">Which of my posts will show up in the fediverse?</li>
+<li class="answer">
+<p>Only the ones you <a href="#send+Bridgy+Fed+a+webmention">explicitly trigger with a webmention</a>. Bridgy Fed doesn't automatically create posts in the fediverse based on your site's Atom feed, HTML, or anything else. It only create posts in the fediverse on an opt in basis, per post, via webmention.
 </p>
 </li>
 
@@ -271,9 +281,16 @@ I love scotch. Scotchy scotchy scotch.
 <p>...just add the id to your page's URL in a fragment, e.g. <code>http://site/post#b</code> here.</p>
 </li>
 
+<li id="backfeed" class="question">How do fediverse replies, likes, and other interactions show up on my site?</li>
+<li class="answer">
+<p>
+To receive likes, reposts, replies, @-mentions, and follows from the fediverse, just make sure your site accepts <a href="https://webmention.net/">webmentions</a>! Bridgy Fed translates those interactions and sends them to your site as webmentions. The source URL will usually be a proxy page on <code>fed.brid.gy</code>. For best results, <a href="https://brid.gy/about#appspot">make sure your webmention handler detects and handles <code>u-url</code> links</a>.
+</p>
+</li>
+
 <li id="read" class="question">How do I read my fediverse timeline/feed?</li>
 <li class="answer">
-<p><a href="/web-site">Your user page</a> has links to your fediverse timeline/feed, ie posts from people you follow, in HTML, Atom, and RSS formats. Add them to your feed reader or read them in your browser!
+<p><a href="#user-page">Your user page</a> has links to your fediverse timeline/feed, ie posts from people you follow, in HTML, Atom, and RSS formats. Add them to your feed reader or read them in your browser!
 </p>
 </li>
 
@@ -285,7 +302,7 @@ I love scotch. Scotchy scotchy scotch.
 
 <li id="troubleshooting" class="question">I tried it, and it didn't work!</li>
 <li class="answer">
-<p><a href="/web-site">Check out your user page!</a> It detects and describes common problems with <a href="#setup">your setup</a>, and it shows your recent interactions and detailed logs.
+<p><a href="#user-page">Check out your user page!</a> It detects and describes common problems with <a href="#setup">your setup</a>, and it shows your recent interactions and detailed logs.
 </li>
 
 
@@ -314,7 +331,7 @@ I'm <a href="https://snarfed.org/">Ryan Barrett</a>. I'm just a guy who likes <a
 
 <li id="history" class="question">How long has this been around?</li>
 <li class="answer">
-<p>I started thinking about bridging federated social networks and peer to peer networks when I discovered them in the early 2000s. I started talking about bridging them to the IndieWeb in 2016, <a href="http://indieweb.org/2017/ostatusbridge">led a session on it at IndieWeb Summit</a> in July 2017, wrote up <a href="https://snarfed.org/indieweb-activitypub-bridge">concrete</a> <a href="https://snarfed.org/indieweb-ostatus-bridge"> designs</a> soon after, and started working on Bridgy Fed in August 2017.
+<p>I started thinking about bridging federated social networks and peer to peer networks when I discovered them in the early 2000s. I started talking about bridging them to the IndieWeb in 2016, <a href="http://indieweb.org/2017/ostatusbridge">led a session on it at IndieWeb Summit</a> in July 2017, wrote up <a href="https://snarfed.org/indieweb-activitypub-bridge">concrete</a> <a href="https://snarfed.org/indieweb-ostatus-bridge"> designs</a> soon after, started working on Bridgy Fed in August 2017, and <a href="https://snarfed.org/2017-10-22_bridgy-fed">launched it on October 22, 2017</a>.
 </li>
 
 <li id="terms" class="question">What are the terms of service?</li>