How to build help documentation using Sandcastle – XML comments

After building XML Comments / Documentation and viewing these in a browser it may be useful to create documentation. Microsoft no longer develop a tool, but a tool Sandcastle they initially developed has continued.

This is some of my experience:

In addition to the normal Sandcastle, I installed the Sandcastle Visual Studio integration package.

Sandcastle have large documentation, but I found the basic steps were:

  1. Open Visual Studio
  2. Add New Project > Documentation > Sandcastle Help File Builder Project
  3. Add Documentation Sources – Reference to the project you want to document
  4. Build the project
  5. To view your new help file
    1. Use Menu > View > View Help File
    2. Or Open the Folder Location and open the Help folder
  6. Find the file ContentLayout.content
    1. Change the title from [TODO]
  7. You may get a lot of warnings and lots of ‘Red’ ‘missing documentation’
    1. To suppress these use Properties > Missing Tags and uncheck warning
    2. Or to use it to find missing documentation, uncheck
  8. All seems good so far.

See also

Sandcastle

XML Documentation

MSDN

Advertisements

User Standards for Documents

User Standards for Documents

Introduction

The originator of a document would ideally bring documents up to a certain standard before distribution. If this is not done then each recipient may need to bring the document up to standard themselves.

It is also good courtesy to send people well-structured documents.

Data Redundancy (duplicated data)

Ideally data is stored once. Distributing a file, especially by email, has the effect of creating multiple copies of the same data in different places, each of which may then be altered independently.

It is good to be aware of possible discrepancies between copies.

One solution is to have a central location for files.

A better solution is to use a central database

Excel

General Standards

  1. Save with the cursor at the most appropriate position. Normally the first sheet A1.

Standards for Documents that may require printing

  1. If it is likely that the sheet may be printed, then set column widths and margins appropriately before saving so that the sheet will print in one sheet wide
  2. If appropriate add gridlines
  3. If appropriate add titles to the header, page numbers and dates and possibly the sheet or file name to the footer as well

For most data including:

Data that may need to be Sorted, Filtered, Imported or require Sums or Pivots

  1. Each column to have a heading in a single cell
  2. No column gaps
  3. No row gaps
  4. Single top row
  5. Freeze panes normally somewhere in row 2 so that the top row is frozen. If the first column or two contains code name or key data and in particular if there are more columns than fit on the screen then it may be appropriate to put the frozen cell in B2, C2 or similar

For data that needs to be imported

  1. Each column would have a single cell with no spaces and CapitalLettersAtTheBeginningOfEachWord
  2. First normal form, see below.
  3. If similar data is being imported then put in a single list, not across multiple sheets

Normalize

Examples

  1. Very Bad

  2. Bad:

  3. Better: First Normal Form – 1NF:

    This is an acceptable level for most users.

  4. Good: Higher levels of Normalization:

    This uses multiple tables to remove data duplication. In the example above the film title “Casablanca” appears more than once. If more films were added the actor names would also appear more than once. In the example below the title and actors appear only once and are subsequently referred to by their IDs, in this case in the FilmActor table.