Merge ~snappy-hwe-team/snappy-hwe-snaps/+git/wifi-connect:docs-0.11 into ~snappy-hwe-team/snappy-hwe-snaps/+git/wifi-connect:master

[Kyle Nitzsche]

Docs for wifi-connect 0.11. Reviews appreciated.

Review should be done on built docs:

* cd to docs/
* execute documentation-builder (installed as a snap).
* Open docs/build/index.html

See it here: https://private-fileshare.canonical.com/~knitzsche/wifi-connect/0.11-MR/index.html

You can also get it here: https://private-fileshare.canonical.com/~knitzsche/wifi-connect/wifi-connect-0.11-mr-docs.tar.gz

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 6f4d7ec6e73d43ea3008cd048d9d8e8a7946d325

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1010/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:6f4d7ec6e73d43ea3008cd048d9d8e8a7946d325
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/166/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/216/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/216/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/216/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/216/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1010
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/753
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/779/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/166/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 21413851075237a74e2edf765ce41f1fc51a58a6

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1011/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:21413851075237a74e2edf765ce41f1fc51a58a6
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/167/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/217
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/217
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/217/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/217
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1011
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/754
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/780/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/167/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 6f4d7ec6e73d43ea3008cd048d9d8e8a7946d325

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1012/

[System Enablement Bot (system-enablement-ci-bot)]

FAILED: Continuous integration, rev:6f4d7ec6e73d43ea3008cd048d9d8e8a7946d325
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/168/
Executed test runs:
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/218/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/218/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/218/console
    FAILURE: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/218/console
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1012
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/755
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/781/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/168/rebuild

review: Needs Fixing (continuous-integration)

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Successfully build documentation, rev: 21413851075237a74e2edf765ce41f1fc51a58a6

Generated documentation is available at https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1013/

[System Enablement Bot (system-enablement-ci-bot)]

PASSED: Continuous integration, rev:21413851075237a74e2edf765ce41f1fc51a58a6
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/169/
Executed test runs:
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=amd64/219
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=arm64/219
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=armhf/219
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build/ARCHITECTURE=i386/219
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-docs/1013
    SUCCESS: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-cleanup/756
    None: https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-update-mp/782/console

Click here to trigger a rebuild:
https://jenkins.canonical.com/system-enablement/job/snappy-hwe-snaps-snap-build-prepare/169/rebuild

review: Approve (continuous-integration)

diff --git a/docs/configure.md b/docs/configure.md
new file mode 100644
index 0000000..67188f9
--- /dev/null
+++ b/docs/configure.md
@@ -0,0 +1,174 @@
+---
+title: "Configuration"
+table_of_contents: True
+---
+
+# Configuration methods
+
+Various options can be configured using snapd variables for the wifi-connect snap. 
+
+These options can be defined in a gadget snap. This approach is appropriate for those who want to integrate wifi-connect into an image.
+
+These options can also be set in terminal.
+
+## Preconfiguration in gadget.yaml
+
+When you pre-install wifi-connect snap into an image, you can use the gadget snap's [gadget.yaml](https://docs.ubuntu.com/core/en/reference/gadget) file to pre-configure certain options. You use the ```defaults``` section to set snapd variables for wifi-connect snap. When wifi-connect is installed, it's configure hook script reads the appropriate snapd variables (if any) and uses their values to set options accordingly.
+
+To use this approach, you need to know the snap-id of the wifi-connect snap. This can be obtained with ```snap info wifi-connect```.
+
+You also need the key name and the value for each configuration option the, as covered below.
+
+## Configuration from terminal
+
+In general, you can set these configuration options at runtime from terminal with:
+
+```bash
+$ sudo snap set wifi-connect KEY=VALUE
+```
+
+**Note**: In many cases, setting wifi-connect snapd variables does not take effect until wifi-connect is restarted. Restart it manually with:
+
+```bash
+sudo snap restart wifi-connect
+``` 
+
+**Note**: When the deamon starts, it logs any preconfigurations found and applied, for example:
+
+```bash
+Jun 20 22:07:16 thehost snap[18004]: == wifi-connect/SetDefaults portal password being set
+Jun 20 22:07:16 thehost snap[18004]: == wifi-connect/SetDefaults: reset creds requirement is now disabled
+```
+
+# AP passphrase
+
+Normally the wifi-connect AP passphrase is randomly created by the wifi-ap snap. 
+
+Preset the passphrase in the gadget.yaml ```defaults``` section with the following:
+
+ * snapd key: wifi.security-passphrase
+ * value: the passhrase (8-13 characters, must start with a letter)
+
+For example:
+
+```bash
+defaults:
+  UGPDdo1mCPUIPOEH3CCCH1ykvB8S0OhB:
+    wifi.security-passphrase: THISISTHENEWAPPASSPHRASE
+```
+
+Note: long alpha-numeric string is the wifi-connect snapd-id (currently). 
+
+You can set this from terminal as follows:
+
+```bash
+$ sudo snap set wifi-connect wifi.security-passphrase=THISISTHENEWAPPASSPHRASE
+``` 
+
+# AP SSID
+
+By default, the AP's SSID is (currently) "Ubuntu". 
+
+You can set this from the terminal as follows:
+
+```bash
+$ sudo wifi-connect passphrase THISISTHENEWAPPASSPHRASE
+``` 
+
+This cannot currently be configured from the gadget.yaml.
+
+# Portal password 
+
+To access any wifi-connect web page you need to enter the portal password. 
+
+Note: the password must be 8 to 13 chars in length, and it must start with a letter.
+
+Preset the portal password in the gadget.yaml ```defaults``` section with the following:
+
+ * snapd key: portal.password
+ * value: the password
+
+For example:
+
+```bash
+defaults:
+  UGPDdo1mCPUIPOEH3CCCH1ykvB8S0OhB:
+    portal.password: THENEWPASSWORD
+```
+
+You can set this from terminal as follows:
+
+```bash
+$ sudo snap set wifi-connect portal-password=THENEWPORTALPASSWORD
+```
+
+# Disable credential resetting
+
+Normally, the first user to access the Management web page is required to reset the wifi-connect AP passphrase and the portal password (used to access wifi-connect web pages). This is a useful security feature, especially for integrators that preset these credential in their image (because every image has the same passphrase and password). 
+
+However, some integrators may want to disable this requirement. 
+
+Disable the requirement to reset the AP passphrase and portal password on first use in the gadget.yaml ```defaults``` section with the following:
+ 
+ * snapd key: portal.no-reset-creds
+ * value: true
+
+For example:
+
+```bash
+defaults:
+  UGPDdo1mCPUIPOEH3CCCH1ykvB8S0OhB:
+    portal.no-reset-cred: true
+```
+
+You can set this from terminal as follows:
+
+```bash
+$ sudo snap set wifi-connect portal.no-reset-cred=true
+```
+
+# Enble display of the Operational Portal
+
+The Operational portal can be enabled so that it is available when the device is connected to an external AP. 
+
+It provides a button the user can click to disconnect from the external AP, which causes the system to switch to Unconnected mode. By default, the Operational portal is disabled. When the page is disabled one must use the terminal (or some other means) to direct the device to disconnect form the external AP.
+
+The Operational portal is disabled by default because using it requires entering the portal password and communications are http, not https. 
+
+**Warning**: Enabling the Operational portal represents a potential security vulnerability because the portal password is conveyed in clear text in the http header.
+
+
+Disable the Operational portal as follows:
+
+ * snapd key: portal.operational
+ * value: true
+
+For example:
+
+```bash
+defaults:
+  UGPDdo1mCPUIPOEH3CCCH1ykvB8S0OhB:
+    portal.operational: true
+```
+
+You can set this from terminal as follows:
+
+```bash
+$ sudo snap set wifi-connect portal.operational=true
+```
+
+# Additional AP configurations
+
+You can set and set various AP configurations. 
+
+View them all with:
+
+```bash
+$ sudo wifi-ap.config get
+```
+
+Set with:
+
+```bash
+$ sudo wifi-ap.config set KEY=VAULE
+```
diff --git a/docs/faq.md b/docs/faq.md
index ec8f87e..75cb029 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -3,8 +3,28 @@ title: "Frequently asked questions"
 table_of_contents: True
 ---
 
-# Restarting the wifi-connect daemon
+# Where do I file a bug?
+
+https://bugs.launchpad.net/snappy-hwe-snaps
+
+Please add the follow **Tag** in **Extra Options**: "wifi-connect"
+
+# How do I request features?
+
+You may file a bus as described above.
+
+# How do I restarting the wifi-connect daemon?
 
 ```bash
-sudo systemctl restart snap.wifi-connect.daemon.service
+sudo snap restart wifi-connect
 ```
+
+# How do I view relevant log messages?
+
+```bash
+$ sudo journalctl -f | grep wifi-connect
+```
+
+# How do I use a different interface for Wi-Fi?
+
+The current hard coded default is wlan0.
diff --git a/docs/features.md b/docs/features.md
new file mode 100644
index 0000000..1108429
--- /dev/null
+++ b/docs/features.md
@@ -0,0 +1,36 @@
+---
+title: "Getting Started"
+table_of_contents: True
+---
+
+# First steps
+
+
+
+
+Wifi-connect requires a passphrase to join the AP. This can be pre-configured in your system. 
+
+
+## C
+
+On first use, 
+
+# Portal Password
+
+wifi-connect has web pages ("portals") that require a password. 
+
+The normal 
+
+# Disconnecting from external AP
+
+When the system is connected to an external AP, wifi-connect does nothing and leaves the connection alone. 
+
+If the external AP connection disappears, wifi-connect takes control and puts up the local AP, which allows a user to join and use the web page to join a new external AP. 
+
+There are two ways to disconnect from an external AP.
+
+## Operational portal
+
+The Opertaional portal is an optional web page wifi-connect can put up when the device is connected. This simple password
+
+
diff --git a/docs/how_it_works.md b/docs/how_it_works.md
new file mode 100644
index 0000000..842a4c7
--- /dev/null
+++ b/docs/how_it_works.md
@@ -0,0 +1,31 @@
+---
+title: "How it works"
+table_of_contents: True
+---
+
+# How it works
+
+## Connection to an external AP
+
+The wifi-connect daemon continuously checks Wi-Fi connected state. 
+
+When there is no external WiFi connection, wifi-connect puts up its own Wi-Fi AP and web page. This is called "management" mode.
+
+You can join the device's AP and open a device web page that lists external APs. 
+
+The web page URL is (by default) http://10.0.60.1:8080 (You can also access the page over Avahi as described elsewhere.)
+
+In ths management web page, you can select an AP and join it with a passphrase. The hosted AP is taken down. the wlan0 interface is put under control of Network Manager, and the device joins the speficied AP. If it cannot join, the daemon removes wlan0 from Network Manager's control and starts the device AP, at which point you can re-join, open the web page, and try again.
+
+![Overview](media/overview.png)
+
+## Disconnection from an external AP
+
+The wifi-connect daemon monitors whether there is any Wi-Fi connection. If it finds one, the daemon does nothing, and the system remains connected to the external AP. This is called "operational" mode.
+
+(If no external Wi-Fi connection is found, the daemon puts the system in Management mode, as described above.)
+
+You can disconnect the system from an external AP in various ways. 
+
+* You can enable the Operational web page, displayed when you are connected to the external AP. This page has a Disconnect button. **Note**: the Operational portal is disabled by default. See [Configuration](configure.html).
+* You can use Network Manager to disconnect (for example over DBus or using nmcli command). You can also use a wifi-connect command: this requires ssh to the system. 
diff --git a/docs/index.md b/docs/index.md
index 679b180..c35cb83 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -5,20 +5,27 @@ table_of_contents: True
 
 # Overview
 
-The wifi-connect snap allows you to connect your device to an external Wi-Fi access point. It does this by putting up its own Wi-Fi AP and web page. You join the AP and the web page lists external APs, which you can then select and join. 
+Wifi-connect is a solution for connecting an IoT device to an external Wi-Fi Access Point without any wired network connections.
 
-Wifi-connect is appropriate for simple use cases where there is no other control of networking. Wifi-connect has a daemon that takes over networking and controls device state automatically:
+It can be installed manually. It is also suitable for integration into Ubuntu Core images. Please contact Canonical for integration information.
 
- * When there is no external AP connection, wifi-connect starts its own AP and the Management web page (which allows you to select and join external WiFI APs)
- * When there is an external AP connection, wifi-connect ensures its own AP is down and puts up the Operational web page (which allows you to disconnect from the external AP) 
+## Use cases
 
-Wifi-connect uses two other snaps:
+Wifi-connect is a good match for many use cases typical of many IoT deployments. 
 
- * wifi-ap: provides the AP function
- * network-manager: handles networking (as a part of installation, the device netplan is modified to make network-manager the renderer for all networking).
+Wifi-connect takes control of some networking on the device, so you should verify expected functionality if other entities control networking to ensure they work well together.
 
-Wifi-connect can be:
+## Required snaps
 
- * Installed at run time
- * Integrated into an image, with options. See "Integrating into an Image" section
+wifi-ap and network-manager snaps must be installed. 
+
+Certain snapd interfaces must be connected, and other steps must be taken. See [Installation](installation.html).
+
+## Security
+
+To use the Management web page (described below), you have to join the AP first. The AP is passphase protected and the passphrase is not (by default) preset in the system (although you can preconfigre it at your descretion and risk).
+
+The Management web page itself is password protected, but the connection is currently http, thus the password is conveyed in clear text in the http header. You may consider this sufficient because the traffic is between you and the system over its own Wi-Fi network that requires a passphrase to join.
+
+The Operational web page is also password protected, and is disabled by default. If you enable it, ensure you understand that the password is sent to the device in clear text in the http header and through the external AP's Wi-Fi network. 
 
diff --git a/docs/installation.md b/docs/installation.md
index deba1ec..f0693a9 100644
--- a/docs/installation.md
+++ b/docs/installation.md
@@ -3,19 +3,22 @@ title: "Installation"
 table_of_contents: True
 ---
 
-# Overview
+# Options
 
-The wifi-connect snap is currently publish in edge and beta channels.
+You can install wifi-connect manually on a Core system over SSH. 
 
-## Install snaps
+You can also integrate wifi-connect into an image. This typically requires connecting the specified snapd interfaces and preseeding the netplan file mentioned below. Please contact Canonical for additional information.
+
+# Install snaps
 
 ```bash
 snap install wifi-ap
 snap install network-manager
-snap install --edge|beta wifi-connect
+snap install wifi-connect
 ```
+Note: If wifi-connect is not yet published in the stable channel, specify the channel at installation time.
 
-## Connect interfaces
+# Connect interfaces
 
 ```bash
 snap connect wifi-connect:control wifi-ap:control
@@ -24,9 +27,7 @@ snap connect wifi-connect:network-bind core:network-bind
 snap connect wifi-connect:network-manager network-manager:service
 ```
 
-## Set NetWorkManager to control all networking
-
-**Note**: This is a temporary manual step before network-manager snap provides a config option for this.
+# Set NetWorkManager to control all networking
 
 **Note**: Depending on your environment, after this you may need to use a new IP address to connect to the device.
 
@@ -43,15 +44,16 @@ snap connect wifi-connect:network-manager network-manager:service
         network:
             renderer: NetworkManager
 
-## Reboot
+# Reboot
 
-Rebooting addresses a potential content sharing interface issue. 
+Rebooting consolidates all networking into NetworkManager.
 
-Rebooting also consolidates all networking into NetworkManager.
+```bash
+$sudo reboot
+```
 
-## Optionally configure wifi-ap SSID/passphrase
+# Set the hosted AP's SSID and passphrase
 
-If you skip these steps, the wifi-AP put up by the device has an SSID of "Ubuntu" and is unsecure (with no passphrase). 
 
  1. Set the wifi-ap AP SSID
 
@@ -61,7 +63,7 @@ If you skip these steps, the wifi-AP put up by the device has an SSID of "Ubuntu
 
         sudo  wifi-connect passphrase MYPASSPHRASE
 
-## Display the AP config
+# Optionally display the AP config
 
 ```bash
 sudo  wifi-connect show-ap
@@ -72,7 +74,9 @@ sudo  wifi-connect show-ap
     dhcp.range-start: 10.0.60.2
     dhcp.range-stop: 10.0.60.199
 
-## Set the portal password
+After connecting to the AP, you open its web page at the address just before the start of the dhcp-range, that is: 10.0.60.10 (on port 8080). So in your browser you enter 10.0.60.1:8080
+
+# Set the portal password
 
 The portal password must be entered to access wifi-connect web pages.
 
@@ -80,42 +84,3 @@ The portal password must be entered to access wifi-connect web pages.
 sudo  wifi-connect set-portal-password PASSWORD
 ```
 
-## Join the device AP
-
-When the device AP is up and available to you, join it.
-
-## Open the the Management portal web page
-
-This portal displays external wifi APs and let's you join them.
-
-After you connect to the device AP, you can open its http portal at the .1 IP address just before the start of the DHCP range (see previous steps) using port 8080: 
-
-    10.0.60.1:8080
-
-You then need to enter the portal password to continue.
-
-### Avahi and hostname
-
-You can also connect to the device's web page using the device host name: 
-
-    http://HOSTNAME.local:8080 
-
-Where HOSTNAME is the hostname of the device when it booted. (Changing hostname with the hostname command at run time is not sufficient.) 
-
-**Note**: The system trying to open the web page must support Avahi. Android systems may not, for example.
-
-## Be patient, it takes minutes
-
-Wifi-connect pauses for about a minute at daemon start to allow any external AP connections to complete.
-
-## Disconnect from wifi
-
-When connected to an external AP, the Operational portal is available on the device IP address (assigned by the external AP). Open it using IP:8080, enter the portal password, and you may then disconnect with the "Disconnect from Wifi" button.
-
-You can also ssh to the device and:
-
- * Use `nmcli c` to display connections.
- * Use `nmcli c delete CONNECTION_NAME` to disconnect and delete. This puts the device into management mode, bringing up the AP and portal.
-
-Disconnecting sets the device back in Management mode. Its AP is started and you can open the portal (as discussed above) to see external APs and connect to one.
-
diff --git a/docs/integrate.md b/docs/integrate.md
deleted file mode 100644
index b1cdd4f..0000000
--- a/docs/integrate.md
+++ /dev/null
@@ -1,70 +0,0 @@
----
-title: "Integrating into an image""
-table_of_contents: True
----
-
-# Overview
-
-When you pre-install wifi-connect snap into an image, you can use the gadget snap's [gadget.yaml](https://forum.snapcraft.io/t/the-gadget-snap/696) file to pre-configure some options.
-
-Here we explain the snap key and value needed to preconfigure.  Refer to the above like for details on how to set these in the gadget snap's gadget.yaml file. 
-
-You may also set these at run time from terminal with:
-
-```bash
-$ snap set wifi-connect KEY=VALUE
-```
-
-To apply such run-time changes, see the Frequently asked questions page.
-
-**Warning**: These changes may create security risks. Only use take these steps if you are completely aware of take responsitbility for the potential risk.
-
-
-**Note** When the deamon starts, it logs any preconfigurations found and applied, for example:
-
-```bash
-Jun 20 22:07:16 thehost snap[18004]: == wifi-connect/SetDefaults portal password being set
-Jun 20 22:07:16 thehost snap[18004]: == wifi-connect/SetDefaults: reset creds requirement is now disabled
-```
-
-## AP passphrase
-
-Normally the wifi-conect AP's passphrase is randomly created by the wifi-ap snap. A normal part of the installation process is resetting this from the terminal. However, some integrators may want to preset the passphrase. 
-
-Preset the passphrase with the following:
-
- * snapd key: wifi.security-passphrase
- * value: the passhrase (8-13 characters, must start with a letter)
-
-## Portal password 
-
-To access any wifi-connect web page you need to enter the portal password. A normal part of the installation process is setting this from the terminal. However, some integrators may want to preset the portal password.  
-
-Preset the portal password  with the following:
-
- * snapd key: portal.password
- * value: the password (8-13 characters, must start with a letter)
-
-## Disable credential resetting
-
-Normally, the first user to access the Management portal is required to reset the wifi-connect AP passphrase and the portal password (used to access wifi-connect web pages). This is an important security feature, especially for integrators that preset these in their image because every image has the same passphrase and password. 
-
-However, some integrators may want to disable this requirement. 
-
-Disable the requirement to reset the AP passphrase and portal password on first use of the Management portal as follows:
- 
- * snapd key: portal.no-reset-creds
- * value: true
-
-## Disable display of the Operational Portal
-
-The Operational portal is available when the device is connected to an external AP. It provides a button the user can click to disconnect. Display of this page can be disabled. This is a normal part of wifi-connect. When the page is disabled one must use the terminal (or some other means) to direct the device to disconnect form the external AP.
-
-Disable the Operational portal as follows:
-
- * snapd key: portal.no-opertaional
- * value: true
-
-
-
-
diff --git a/docs/media/config.png b/docs/media/config.png
new file mode 100644
index 0000000..b8ddd8e
Binary files /dev/null and b/docs/media/config.png differ
diff --git a/docs/media/connect.png b/docs/media/connect.png
new file mode 100644
index 0000000..bf9134b
Binary files /dev/null and b/docs/media/connect.png differ
diff --git a/docs/media/disconnect.png b/docs/media/disconnect.png
new file mode 100644
index 0000000..6093a08
Binary files /dev/null and b/docs/media/disconnect.png differ
diff --git a/docs/media/mgmt.png b/docs/media/mgmt.png
new file mode 100644
index 0000000..f6146b6
Binary files /dev/null and b/docs/media/mgmt.png differ
diff --git a/docs/media/overview.png b/docs/media/overview.png
new file mode 100644
index 0000000..075dc7d
Binary files /dev/null and b/docs/media/overview.png differ
diff --git a/docs/media/portal_password.png b/docs/media/portal_password.png
new file mode 100644
index 0000000..ddb18dc
Binary files /dev/null and b/docs/media/portal_password.png differ
diff --git a/docs/metadata.yaml b/docs/metadata.yaml
index 2fb6ea0..081b31f 100644
--- a/docs/metadata.yaml
+++ b/docs/metadata.yaml
@@ -4,9 +4,15 @@ navigation:
   - title: Introduction
     location: index.md
     children:
+    - title: How it works 
+      location: how_it_works.md
     - title: Installation
       location: installation.md
-    - title: Integrating into an image
-      location: integrate.md
-    - title: Frequently asked questions
+    - title: Configuration
+      location: configure.md
+    - title: Usage
+      location: normal_use.md
+    - title: FAQ
       location: faq.md
+    - title: About 
+      location: revisions.md
diff --git a/docs/normal_use.md b/docs/normal_use.md
new file mode 100644
index 0000000..2e67d68
--- /dev/null
+++ b/docs/normal_use.md
@@ -0,0 +1,91 @@
+---
+title: "Usage"
+table_of_contents: True
+---
+
+# Usage
+
+This section covers normal usage, including:
+
+* Joining the device AP
+* Selecting and joining an external AP
+* Disconnecting from the external AP
+ 
+# Join the device AP
+
+When the device AP is up and available to you, join it from your laptop, smartphone or similar. 
+
+Use the SSID set previously (or the default of "Ubuntu"), and use the passphrase set previously (a prerequisite).
+
+# Open the the wifi-connect web page
+
+This page displays external Wi-Fi APs and let's you select and join one.
+
+After you connect to the device's AP, you can open its web page at the .1 IP address just before the start of the DHCP range (see previous steps) using port 8080: 
+
+    10.0.60.1:8080
+
+**Note**: The screenshots that follow use an Avahi address instead of the IP address, as explained next.
+
+Enter the portal password previously configured to continue.
+
+![portal password](media/portal_password.png)
+
+
+## Connecting through Avahi and hostname
+
+You can also connect to the device's web page using the device host name when you are on the same IP subnet as the device: 
+
+    http://HOSTNAME.local:8080 
+
+Where HOSTNAME is the hostname of the device when it booted. (Changing hostname with the hostname command at run time is not sufficient.) 
+
+**Note**: The system trying to open the web page must support Avahi. Android systems may not, for example.
+
+## Be patient, it takes minutes
+
+Wifi-connect pauses for about a minute at daemon start to allow any external AP connections to complete.
+
+# First run configuration
+
+On first use, the web page displays a configuration form that may require some input.
+
+**Note**: An automatic reboot may be required. 
+
+![configuration page](media/config.png)
+
+# Select an AP to join
+
+The landing page displays external APs. Select one.
+
+![landing page](media/mgmt.png)
+
+# Enter Passphrase and join
+
+Enter the passphrase, and confirm to join it:
+
+![landing page](media/mgmt.png)
+
+
+# Disconnect from Wi-Fi
+
+## Operational portal is off
+
+As noted elsewhere, any method can be be used do disconnect the Wi-Fi connection and wifi-connect recovers, returning to Management mode.
+
+For example: You can also ssh to the device and:
+
+ * Use `nmcli c` to display connections.
+ * Use `nmcli c delete CONNECTION_NAME` to disconnect and delete. This puts the device into management mode, bringing up the AP and portal.
+
+You can also implement code that makes a DBus call to Network Manager to disconnect. 
+
+## Operational portal is on
+
+When connected to an external AP, the Operational portal, if enabled, is available on the device IP address (assigned by the external AP), (or through Avahi when on the same IP subnet, as mentioned above). 
+
+Open it using IP:8080, enter the portal password, and you may then disconnect with the **Disconnect from Wifi** button.
+
+Disconnecting sets the device backto starting mode. Its AP is started and you can join and open the web page (as discussed above) to see external APs and connect to one.
+
+![disconnect page](media/disconnect.png)
diff --git a/docs/revisions.md b/docs/revisions.md
new file mode 100644
index 0000000..2d29b49
--- /dev/null
+++ b/docs/revisions.md
@@ -0,0 +1,6 @@
+---
+title: "About"
+table_of_contents: true
+---
+
+This document is written for wifi-connect version 0.11
diff --git a/hooks/configure.go b/hooks/configure.go
index e34cd45..80cfe91 100644
--- a/hooks/configure.go
+++ b/hooks/configure.go
@@ -117,12 +117,12 @@ func main() {
 
 	b, err := json.Marshal(preConfig)
 	if err != nil {
-		log(" Marshall error:" + err.Error())
+		log("Marshall error: " + err.Error())
 		return
 	}
 
 	err = ioutil.WriteFile(daemon.PreConfigFile, b, 0644)
 	if err != nil {
-		log("configure error: " + err.Error())
+		log("configure hook: " + err.Error())
 	}
 }