-Addon names cannot contain spaces or other punctuation and are used as filenames and function names.
-You may supply a "friendly" name within the comment block.
-Each addon must contain both an install and an uninstall function based on the addon name.
-For instance "addon1name_install()".
-These two functions take no arguments and are usually responsible for registering (and unregistering) event hooks that your addon will require.
-The install and uninstall functions will also be called (i.e. re-installed) if the addon changes after installation.
-Therefore your uninstall should not destroy data and install should consider that data may already exist.
-Future extensions may provide for "setup" amd "remove".
+## Naming
+
+Addon names are used in file paths and functions names, and as such:
+- Can't contain spaces or punctuation.
+- Can't start with a number.
+
+## Metadata
+
+You can provide human-readable information about your addon in the first multi-line comment of your addon file.
+
+Here's the structure:
+
+```php
+/**
+ * Name: {Human-readable name}
+ * Description: {Short description}
+ * Version: 1.0
+ * Author: {Author1 Name}
+ * Author: {Author2 Name} <{Author profile link}>
+ * Maintainer: {Maintainer1 Name}
+ * Maintainer: {Maintainer2 Name} <{Maintainer profile link}>
+ * Status: {Unsupported|Arbitrary status}
+ */
+```
+
+You can also provide a longer documentation in a `README` or `README.md` file.
+The latter will be converted from Markdown to HTML in the addon detail page.
+
+## Install/Uninstall