Add documentation

README.md

@@ -1,4 +1,30 @@
-# Usage
+# XML Schema Documenter
+
+XML Schema Documenter is a [Sandcastle Help File Builder][shfb] plug-in that
+allows you to integrate reference documentation for XML schemas in your help
+files.
+
+## Features
+
+* XML Schema Documenter allows you to easily create XML schema documentation by
+  extending [Sandcastle Help File Builder][shfb].
+* XML Schema Documenter automatically utilizes the standard
+  [annotation Element](http://www.w3.org/TR/xmlschema-0/#CommVers) for summary
+  documentation.
+* You can leverage the power of Microsoft Assistance Markup Language (MAML) for
+  documenting your XML schema items.
+* Since XML Schema Documenter emits the documentation as MAML the output style
+  is always consistent with the rest of your help file.
+* You can document your XML schemas either inline or in an external
+  documentation file.
+* Using a custom XSLT transform you can easily create or reuse your own inline
+  documentation format.
+* You can effectively cross-link your XML schema with your MAML documentation
+  using the MAML `link` element and the new `xmlEntityReference` element.
+
+![](docs/Screenshot.png)
+
+## Usage
 
  1. Install [Sandcastle Help File Builder (SHFB)][shfb]
 
@@ -10,17 +36,17 @@
 
  3. Read the [documentation][docs]
 
-# Development
+## Development
 
-## Prerequisites
+### Prerequisites
 
  1. [Microsoft Visual Studio 2013 (Professional, Premium or Ultimate)][vs].
 
  2. [Sandcastle Help File Builder (SHFB)][shfb]
-   
+
  3. [Windows Installer XML (WiX) toolset Version 3.8][wix]
-  
-## Building
+
+### Building
 
 1. Run `build.cmd`
 
@@ -29,19 +55,19 @@
    - `raw`. Contains the binaries (compiled in `Release` configuration).
    - `release`. Contains the zipped setup, samples, and source code.
    - `samples`. Contains several sample .chm files.
-   - `setup`. Contains the setup.   
+   - `setup`. Contains the setup.
    - `src`. Contains the complete source code.
 
 [shfb]: http://shfb.codeplex.com/releases
-[xsddoc]: http://xsddoc.codeplex.com/releases
-[docs]: http://xsddoc.codeplex.com/documentation
+[xsddoc]: https://github.com/terrajobst/xsddoc/releases
+[docs]: docs/Documentation.md
 [vs]: http://msdn.microsoft.com/en-us/vstudio/default.aspx
 [wix]: http://wix.codeplex.com/releases/view/115492
 
-## To be done
+### To be done
 
-- xmlEntityLink: should render bold when the target is the current topic.
+- `xmlEntityLink`: should render bold when the target is the current topic.
 - Investigate how we can use shared content for localization
 - Consider qualifying names within parents/usages so that they are unqiue.
 - Redefinition?
-- Substitution groups?
+- Substitution groups?

docs/Documentation.md

@@ -0,0 +1,44 @@
+# Documentation
+
+## Getting Started
+
+### Installing Prerequisites
+
+First, you need to download [Sandcastle Help File Builder (SHFB)][SHFB]. This
+tool provides a guided installer package that allows you to properly install all
+components required for Sandcastle and the help file builder. Make sure you
+install the following components:
+
+* Sandcastle Help File Builder
+* At least one help compiler (HTML Help 1 or Microsoft Help 2)
+
+### Installing XML Schema Documenter
+
+After you installed SHFB make sure you reboot the machine. This is necessary to
+ensure all environment variables added by the installer can be accessed. Then,
+download and run the [XML Schema Documenter setup][XSDOC-Releases].
+
+### Using the Plug-In
+
+In order to use the plug-in, start SHFB and add the plug-in to your project:
+
+![](XsdDocPlugin.png)
+
+In Visual Studio it looks similar:
+
+![](XsdDocVS.png)
+
+## Documentation
+
+The installation of the XML Schema Documenter plug-in comes with a comprehensive
+help file that explains how XML schemas can be documented. It can be found here:
+
+    %ALLUSERSPROFILE%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins\XML Schema Documenter\Help.chm
+
+You can also access the help from any of the dialogs provided by the plug-in by
+clicking on the question mark icon:
+
+![](XsdDocConfig.png)
+
+[SHFB]: http://shfb.codeplex.com/releases
+[XSDOC-Releases]: https://github.com/terrajobst/xsddoc/releases