1 files changed, 93 insertions, 0 deletions
diff --git a/doc/README.documentation.adoc b/doc/README.documentation.adoc
new file mode 100644
index 00000000..850a870a
--- /dev/null
+++ b/doc/README.documentation.adoc
@@ -0,0 +1,93 @@
+
+:experimental:
+= Introduction
+
+This directory contains the source files needed to build the:
+
+- Wireshark User’s Guide
+- Wireshark Developer’s Guide
+- Release notes
+- Lua Reference
+
+To build everything, build the `all_guides` target, e.g. `ninja
+all_guides` or `msbuild all_guides.vcxproj`. Requirements are listed
+below.
+
+The guides and release notes are written in
+https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[Asciidoctor syntax].
+For more information see https://asciidoctor.org.
+
+== Requirements
+
+Ultimately we'd like to reduce the toolchain requirements to AsciidoctorJ alone, but that's not yet possible.
+Additional tooling is required for the HTML and HTMLHelp targets.
+See the https://www.wireshark.org/docs/wsdg_html_chunked/ChToolsDocumentationToolchain.html[Developer's Guide] for instructions on installing required packages for your platform.
+
+== Asciidoctor Markup
+
+The User’s and Developer’s Guides were originally written in DocBook and
+were later converted to https://asciidoc.org/[AsciiDoc]. We subsequently
+switched from AsciiDoc to Asciidoctor.
+We currently use Asciidoctor’s modern (>= 1.5.0) syntax.
+
+Please use the following conventions when writing documentation:
+
+- Window and dialog box names should be in “curly quotes”.
+
+- Use Asciidoctor macros for buttons, keys, and menus. Note that these
+  are currently experimental:
+
+** The btn:[Start] button
+** Press kbd:[Shift+Ctrl+P] to open the preferences dialog.
+** Select menu:File[Open] from the main menu.
+
+This ensures that UI elements are shown consistently and lets us apply styles
+to each type of element.
+
+- Command line examples should reflect the OS:
++
+----
+$ echo Linux and UNIX
+----
++
+----
+C:\> echo Windows
+----
+
+Admonitions ([NOTE], [TIP], [IMPORTANT], [CAUTION] and [WARNING]) can be used to highlight important
+information. Keep in mind that they interrupt the flow of text by design. Too
+many (especially in a row) are distracting and annoying.
+
+== Custom Asciidoctor Macros
+
+The following custom macros are available in `doc/asciidoctor-macros`:
+
+commaize-block::
+Sorts a list of items and separates them with commas with an "and" preceding the last item.
+
+cveidlink-inline-macro::
+Links a CVE ID to cve.mitre.org.
+
+manarg-block::
+Ensures that individual arguments don't wrap in order to improve readability.
+
+wsbuglink-inline-macro::
+Links an issue number to gitlab.org/wireshark/wireshark/-/issues.
+
+wssalink-inline-macro::
+Links a security advisory to www.wireshark.org.
+
+== Asciidoctor Live Preview
+
+The Asciidoctor project provides a JavaScript version of Asciidoctor
+(asciidoctor.js), which enables live previews in many web browsers and
+text editors. See the
+https://asciidoctor.org/docs/editing-asciidoc-with-live-preview/[Live
+Preview] documentation for more information.
+
+Note that our documentation depends on attributes defined in
+_attributes.adoc_. The User’s Guide and Developer’s Guide are split
+across several files, and only the top-level _user-guide.adoc_ and
+_developer-guide.adoc_ include _attributes.adoc_. As a result,
+some markup will be incomplete. You can work around this somewhat by
+adding the `experimental` attribute to your Live Preview settings.