From 6ce42e019ed243a6f984c5c7d37e4b4f09826b76 Mon Sep 17 00:00:00 2001
From: Thomas Sileo <t@a4.io>
Date: Tue, 12 Jul 2022 19:42:31 +0200
Subject: [PATCH] User's guide draft

---
 docs/user_guide.md | 129 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/docs/user_guide.md b/docs/user_guide.md
index f132024..0814d9b 100644
--- a/docs/user_guide.md
+++ b/docs/user_guide.md
@@ -2,6 +2,135 @@
 
 [TOC]
 
+## ActivityPub
+
+Using microblog.pub efficiently requires knowing a bit about how [ActivityPub](https://activitypub.rocks/) works.
+
+Skimming over the [Overview section of the ActivityPub specification](https://www.w3.org/TR/activitypub/#Overview) should be enough.
+
+Also, you should know that the **Fediverse** is a common name used to describe all the interconnected/federated instances of servers supporting ActivityPub (like Mastodon, Pleroma, PeerTube, PixelFed...).
+
+## Configuration
+
+### Profile
+
+You initial profile configuration is generated via the setup wizard.
+
+You can manually edit the configuration file stored in `data/profile.toml` ([TOML](https://toml.io/en/)), note that the following config items cannot be updated (without breaking federation):
+
+ - `domain`
+ - `username`
+
+As these two config items define your ActivityPub handle `@handle@domain`.
+
+You can tweak your profile by tweaking these items:
+
+ - `name`
+ - `summary` (using Markdown)
+ - `icon_url`
+
+Whenever one of these config items is updated, an `Update` activity will be sent to all know server to update your remote profile.
+
+### Customization
+
+TODO
+
+## Public website
+
+Public notes will be visible on the homepage.
+
+Only the last 20 followers/follows you be showing on the public website.
+
+And only the last 20 interactions (likes/shares/webmentions) will be displayed, to keep things simple/clean.
+
+## Admin section
+
+You can login to the admin section by visiting `https://yourdomain.tld/admin` and use the password set during the initial configuration.
+
+### Lookup
+
+The `Lookup` section allows you to interact with any remote remote objects/content on the Fediverse.
+
+The lookup supports:
+
+ - profile page, like `https://testing.microblog.pub`
+ - content page, like `https://testing.microblog.pub/o/4bccd2e31fad43a7896b5a33f0b8ded9`
+ - username handle like `@testing@testing.microblog.pub`
+ - ActivityPub ID, like `https://testing.microblog.pub/o/4bccd2e31fad43a7896b5a33f0b8ded9`
+
+## Authoring notes
+
+Notes are authored in [Markdown](https://commonmark.org/). There is no imposed characters limit.
+
+If you fill the content warning, the note will be automatically marked as sensitive.
+
+You can add attachments/upload files.
+When attaching pictures, EXIF metadata (like GPS location) will be removed automatically before being stored.
+
+Consider marking attachments as sensitive using the checkbox if needed.
+
+## Webmentions
+
+Public notes that link to "Webmention-compatible" website will trigger an outgoing webmention.
+Most websites that support Webmention will display your profile on the mentioned page.
+
+### Fenced code blocks
+
+You can include code blocks in notes,  using the triple backtick syntax.
+
+The code will be highlighted using [Pygments](https://pygments.org/).
+
+Example:
+
+~~~
+Hello
+
+```python
+print("I will be highlighted")
+```
+
+~~~
+
+### Custom emoji
+
+TODO
+
+## Interactions
+
+microblog.pub supports the most common interactions supported by the Fediverse.
+
+### Shares
+
+Sharing an object will relay it to your followers and notify the author.
+It will also be displayed on the homepage.
+
+Most receiving servers will increment the number of shares.
+
+TODO receiving
+
+### Likes
+
+Liking an object will notify the author.
+Unkike sharing, liked object are not displayed on the homepage.
+
+Most receiving servers will increment the number of likes.
+
+TODO receiving
+
+### Bookmarks
+
+Bookmarks allow you to like objects without notifying the author.
+
+It is basically a "private like", and allow you to easily access them later.
+
+TODO receiving
+
+### Webmentions
+
+Sending webmention to ping mentioned website is done automatically once a note is authored, see TODO.
+
+TODO side-effect of receiving a webmention.
+
 ## Backup and restore
 
 All the data generated by the server is located in the `data/` directory: