Tricks and tips for documentation
Document your project is a definitive must to-do but not always the first thing a developer thinks of. It’s something everyone knows is required but in the end something that might be done on the last project hours of the project budget, right? Well there are some things you could do to speed up documentation and semi automate this process. First you need to set the documentation level. Are you required to document on field level or is it enough to explain on a higher level what your new entities or callout classes are supposes to do? If the code is well written I personally don’t require field level documentation and a higher explanation (story) would be enough to understand what your solution is doing (or suppose to do). You also have the possibility to add your comments when adding fields in MSCRM during customizations. This data is stored in the metadatabase and could be exported to excel if wanted.
Solution architect overview - file as vsd is attached in this post
Since I first announced that I would write how-to deliver documentation as chm files I received a note from my friend Michael Höhne telling me that’s “old stuff” and he already blogged about that. So you made this post and I ref your excellent 3 part story.
For editing you chm files you could import the NDOC generated files to HTML help workshop. Here you could edit and add not generated information from NDOC. I recommend adding the vision template (save as GIF) and add under Solution Architect chapter.
Once you compiled the chm file you have almost (or same) professional look a like of documentation as MSDN.
Suggestions on topics for you project SDK
+Your name of tool
-Gettings Started
-Screen shoots of solution
-Flow – sales process
-Flow – marketing process leads
-Flow – ....
+Architecture Overview
-Solution Overview
-Namespaces
-Technical Architecture
-Source Control
+Logical Database Diagram
-Overview
+Deployment
-Deployment Process
-Entity type codes (if you have different setups of CRM servers)
-Client settings (Policy)
-Integration
-Javascript
-Debugging
+Database
-Index and tunings
-Reports
+Callouts
-Customer.Crm.Callout (your NDOC generated class documentation)
Adding new pages to HTML help workshop is an easy task. Below html is an example for MSDN look a like page that works nice with the NDOC generated files. Modify above (attached) architecture.vsd to your solution and save the file as Architecture.gif. Copy the file to the HTML page folder and compile it in the HTML help workshop project.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="https://www.w3.org/1999/xhtml" > <head> <TITLE>Platform Architecture</TITLE> <meta http-equiv="Content-Type" content="text/html; charset=Windows-1252"> <meta name="vs_targetSchema" content="https://schemas.microsoft.com/intellisense/ie5"> <xml></xml> <link rel="stylesheet" type="text/css" href="MSDN.css"> </head> <body id="bodyID" class="dtBODY"> <div id="nsbanner"> <div id="bannerrow1"> <table class="bannerparthead" cellspacing="0" ID="Table1"> <tr id="hdr"> <td class="runninghead"><name of tool or project></td> <td class="product"> </td> </tr> </table> </div> <div id="TitleRow"> <h1 class="dtH1">Solution Architecture v1.0</h1> </div> </div> <div id="nstext"> <IMG SRC="Architecture.gif" ALT="Microsoft CRM V3.0 architecture " BORDER="0"> <BR> <H1><A name="hist"></A>Release History</H1> <P>N/A</P> <FONT size="-1"> <BR> </FONT> <hr> <div id="footer"> <Name of project or tool></div> </div> </body> </html> |
Example of added html file to HTML workshop
editor
Final word from an quote by Dave. I'm not sure I agree but some parts of me laughts :-) Happy documenation
“Software is usually accompanied by documentation in the form of big fat scary manuals that nobody ever reads. In fact, for the past five years most of the manuals shipped with software products have actually been copies of Stephen King's The Stand with new covers pasted on.”
- Dave Barry