Add Admin manual

svn path=/trunk/mono-tools/; revision=74543

docbrowser/Makefile.am

@@ -55,7 +55,8 @@ EXTRA_DIST = \
 	admin.glade 			\
 	browser.glade 			\
 	monodoc.png			\
-	AssemblyInfo.cs
+	AssemblyInfo.cs			\
+	README.ADMIN
 
 # admin hardcodes GTKHTML for now.
 if ENABLE_GTKHTML

docbrowser/README.ADMIN

@@ -0,0 +1,135 @@
+Using the Admin Tool
+====================
+
+	The administration tool is not the most polished piece of
+	software, but these are the instructions on how to use it:
+
+	For you to start using the Administration tool, you must be
+	granted permissions to become an administrator on the Monodoc
+	system site, you must contact Miguel (miguel@novell.com) to
+	gain Monodoc permissions.
+
+Configuring the Tool
+====================
+
+	The Admin tool works by pulling contributions that have been
+	submitted to the web site and allowing you to review the
+	change and apply the change if the change is correct.
+
+	The tool works by patching local copies of the documentation,
+	and those changes must then be committed to the repository
+	before they can be distributed to people.
+
+	This means that you need a Mono Subversion account to be able
+	to check in the documentation and to get fresh copies of the
+	documentation. 
+
+	The tool needs to be configure so it knows how to map
+	contributions in the documentation to your local check out,
+	this is done by creating the file
+	~/.config/monodoc/providers.xml
+
+	The file contents is for example:
+
+		<Providers
+			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
+			xmlns:xsd="http://www.w3.org/2001/XMLSchema">
+		  <Location Name="netdocs" Path="/cvs/monodoc/class"/>
+		  <Location Name="gtk-sharp-docs" Path="/cvs/gtk-sharp/doc"/>
+		  <Location Name="gecko-sharp-docs" Path="/cvs/gtkmozembed-sharp/doc"/>
+		  <Location Name="Novell" Path="/cvs/monodoc/class"/>
+		  <Location Name="Mono" Path="/cvs/monodoc/class"/>
+		  <Location Name="gtksourceview-sharp-docs" Path="/cvs/gtksourceview-sharp/doc"/>
+		  <Location Name="debugger" Path="/cvs/debugger/doc"/>
+		</Providers>
+
+	Here as you can see the configuration file is made to point to
+	the various directories that I have checkout from CVS.
+
+Policies
+========
+
+	People contribute many kinds of changes, and we do not
+	necessarily want all of those changes, changes that are
+	typically OK:
+
+		* Completing missing documentation.
+
+		* Providing illustrative examples.
+
+		* Copy/pasting documentation from the ECMA
+		  specification.   The ECMA specification has been
+		  updated and the license allows us to incorporate
+		  those changes.
+
+		  We have sadly not automated this process and hence
+		  the documentation that we have reflects the first
+		  ECMA release, not the latest one.
+
+		* Pointing out alternative APIs that might be better
+		  suited for a particular task, limitations in an API.
+
+	Changes that are not OK:
+
+		* Long explanations in the summary line that should be
+		  instead in the Remarks section.
+
+		* Sample code in languages other than C#.   People
+	  	  have been picking samples in Boo, Visual Basic,
+		  Jscript and IronPython, but considering that we do
+		  even have complete C# coverage, it is better to keep
+		  all samples in C#.
+
+		* Documentation that has been copy/pasted from
+		  Microsoft documentation.  This means that for every
+		  change that affects the Microsoft stack
+	  	  documentation an editor must verify that the text
+		  for the equivalent class is not the same.
+
+		  This can be a very time consuming operation, and it
+		  is best to not approve a change if you have not
+		  explicitly verified that this is not a copy. 
+
+		* Opinions, these should be kept out of the
+		  documentation, this is a technical document and we
+		  should not be passing value judgments on it.
+
+
+Using the Tool
+==============
+
+	Once you have configured the tool, run the `make c' command in
+	this directory.   This will bring up the administration tool.
+	Click on "Check Server Updates to get updates from the
+	server".
+
+	Many of the early applications are pending review or have some
+	problems but we have not cleared them out yet, so its best to
+	start at the higher numbered contributions which are the
+	freshest. 
+
+	Click on a contribution, it will show you the actual change.
+	The rendering is not perfect, if you want to get further
+	information click [Diff], that will provide a rendering before
+	and after that you can more easily examine.
+
+	When you like a change, click on [Apply], and commit the code
+	properly giving credit on the commit message to the person
+	that made the contribution (you must do this from a separate
+	window where you run svn commit).  [Yes, this could be improved]
+
+	If the contribution is large, also add the contribution to the
+	AUTHORS for that particular bit of documentation.
+
+	Once a contribution has been applied and there is nothing left
+	to use (either because it has been applied, or the
+	contribution has been deemed as invalid) click the [Flag as
+	Done] button that will remove the contribution from the list
+
+Samples in Other Languages
+==========================
+
+	The reality is that we probably need a better system to handle
+	examples, keep those examples off-line so that people can
+	contribute alternative implementations, but at this point we
+	do not have a mechanism to do this.