From 3b561400322eda75f7443e6bb88d7e5dd24336b2 Mon Sep 17 00:00:00 2001
From: danshick <dan.shick@gmail.com>
Date: Wed, 29 Apr 2020 13:50:53 -0400
Subject: [PATCH] Add documentation

Improve the README, add links to the wiki and add a contributing guide.
---
 CONTRIBUTING.md | 19 +++++++++++++++++
 README.md       | 56 ++++++++++++++++++++++++++++++++++++-------------
 2 files changed, 61 insertions(+), 14 deletions(-)
 create mode 100644 CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..3bc63b6
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,19 @@
+# Contributing
+
+We closely follow the wlroots [contributing] guidelines where possible. Please
+see that document for more information.
+
+## Tooling
+
+Useful tools include `dbus-monitor` to watch requests being made,
+and `dbus-send` and the similar `busctl call` for manual dbus calls.
+
+You can test the integration with the [portal-test] Flatpak app.
+
+Alternatively you can trigger it with [trigger-screen-shot.py] and
+[xdp-screen-cast.py].
+
+[contributing]: https://github.com/swaywm/wlroots/blob/master/CONTRIBUTING.md
+[portal-test]: https://github.com/matthiasclasen/portal-test
+[trigger-screen-shot.py]: https://gitlab.gnome.org/snippets/814
+[xdp-screen-cast.py]: https://gitlab.gnome.org/snippets/19
diff --git a/README.md b/README.md
index 0b204d9..dba000f 100644
--- a/README.md
+++ b/README.md
@@ -6,33 +6,61 @@
 
 ## Building
 
-	meson build
-	ninja -C build
+```sh
+meson build
+ninja -C build
+```
 
 ## Installing
 
-	ninja -C build install
+### From Source
+
+```sh
+ninja -C build install
+```
+
+### Distro Packages
+
+#### Arch Linux (AUR)
+
+xdg-desktop-portal-wlr-git
+
+## Running
 
 Make sure `XDG_CURRENT_DESKTOP=sway` is set.
 
-	/usr/lib/xdg-desktop-portal -r &
-	xdg-desktop-portal-wlr
+When correctly installed, xdg-desktop-portal should automatically invoke
+xdg-desktop-portal-wlr when needed.
 
-## Tooling
+At the moment, some command line flags are available for testing, compatibility,
+or output selection. If you need to use one of these flags, you can provide an
+instance of xdpw using the following command:
 
-Useful tools include `dbus-monitor` to watch requests being made,
-and `dbus-send` and the similar `busctl call` for manual dbus calls.
+```/usr/lib/xdg-desktop-portal -r & xdg-desktop-portal-wlr [OPTION...]```
 
-You can test the integration with the [portal-test] Flatpak app.
+To understand the available options, you can run `xdg-desktop-portal-wlr --help`
 
-Alternatively you can trigger it with [trigger-screen-shot.py] and
-[xdp-screen-cast.py].
+## FAQ
+
+Check out or [FAQ] for answers to commonly asked questions.
+
+Please see the [screencast compatibility] guide for more information on
+compatible applications and how to get them working.
+
+If you have a question or problem that is not mentioned in those documents,
+please open an issue or come chat with us in [#sway] on freenode IRC.
+
+## Contributing
+
+If you're interested in testing or development, check out
+[CONTRIBUTING.md] for more information.
 
 ## License
 
 MIT
 
-[portal-test]: https://github.com/matthiasclasen/portal-test
 [xdg-desktop-portal]: https://github.com/flatpak/xdg-desktop-portal
-[trigger-screen-shot.py]: https://gitlab.gnome.org/snippets/814
-[xdp-screen-cast.py]: https://gitlab.gnome.org/snippets/19
+[FAQ]: https://github.com/emersion/xdg-desktop-portal-wlr/wiki/FAQ
+[screencast compatibility]: https://github.com/emersion/xdg-desktop-portal-wlr/wiki/Screencast-Compatibility
+[#sway]: https://webchat.freenode.net/#sway
+[CONTRIBUTING.md]: CONTRIBUTING.md