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.

Part 1

Part 2

Part 3

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.

style='margin-left:3.5pt;border-collapse:collapse;border:none;mso-border-alt:
solid windowtext .5pt;mso-padding-alt:0cm 3.5pt 0cm 3.5pt;mso-border-insideh:
.5pt solid windowtext;mso-border-insidev:.5pt solid windowtext'>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'> 

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'><! style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>DOCTYPE
style='color:red'>html PUBLIC style='color:blue'>"-//W3C//DTD XHTML 1.0 Transitional//EN" style='color:blue'>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>html
style='color:red'>xmlns="http://www.w3.org/1999/xhtml"
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>head
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>TITLE
>Platform Architecture style='color:blue'></TITLE style='color:blue'>>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>meta
style='color:red'>http-equiv="Content-Type"
content="text/html;
charset=Windows-1252">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>meta
style='color:red'>name="vs_targetSchema"
content="http://schemas.microsoft.com/intellisense/ie5">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>xml
></xml lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>link
style='color:red'>rel="stylesheet"
type="text/css"
href="MSDN.css">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>head
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>body
style='color:red'>id="bodyID"
class="dtBODY">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
style='color:red'>id="nsbanner">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
style='color:red'>id="bannerrow1">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>table
style='color:red'>class="bannerparthead"
cellspacing="0"
ID="Table1">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'>            style='color:blue'><tr style='color:red'>id="hdr">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'>                         style='color:blue'><td style='color:red'>class="runninghead">< style='color:maroon'>name of style='color:red'>tool or style='color:red'>project></ style='color:maroon'>td>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'>                         style='color:blue'><td style='color:red'>class="product">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'>                         style='color:blue'></td style='color:blue'>>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'>            style='color:blue'></tr style='color:blue'>>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>table
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
style='color:red'>id="TitleRow">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>h1
style='color:red'>class="dtH1">Solution
Architecture v1.0</h1>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
style='color:red'>id="nstext">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>IMG
style='color:red'>SRC="Architecture.gif"
ALT="Microsoft CRM
V3.0 architecture "
BORDER style='color:blue'>="0">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>BR
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>H1
><A lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";mso-ansi-language:
EN-GB;mso-no-proof:yes'> name style='color:blue'>="hist"></A style='color:blue'>>Release History</ style='color:maroon'>H1>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>P
>N/A</ style='color:maroon'>P>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>FONT
style='color:red'>size="-1">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>BR
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'></ style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>FONT
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>hr
>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>div
style='color:red'>id="footer">

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'>< style='font-size:8.0pt;font-family:"Courier New";color:maroon;mso-ansi-language:
EN-GB;mso-no-proof:yes'>Name
style='color:red'>of project style='color:red'>or tool style='color:blue'>></div style='color:blue'>>

style='font-size:8.0pt;font-family:"Courier New";color:blue;mso-no-proof:
yes'></div>

style='font-size:8.0pt;font-family:"Courier New";color:blue;mso-no-proof:
yes'></body>

style='font-size:8.0pt;font-family:"Courier New";color:blue;mso-no-proof:
yes'></html>

lang=EN-GB style='font-size:8.0pt;font-family:"Courier New";color:blue;
mso-ansi-language:EN-GB;mso-no-proof:yes'> 

Example of added html file lang=EN-GB style='font-size:8.0pt;mso-ansi-language:EN-GB'> 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

Solution Arch.vsd

Comments (2)

  1. jeanlara02 says:

    Your post is very informational. I would love to read other related posts. Can you give me other links for topics such as yours?

    thanks,

    Jean

Skip to main content