Sent: Tuesday, February 12, 2013 11:49 AM

To: Development
Cc: Quality Assurance; IT Managers
Subject: What has Sylecop done for me lately?

Project documentation is here!  Project documentation is here!  Project documentation is here!

See a sample at http://mirsrvdevweb03/help

I know that you are all excited about this!

FAQ
How did StyleCop help this documentation?
StyleCop enforces, amongst other things, inline documentation in our code base.  In the projects where
we have applied style, there is only a few more steps to get the type of documentation.

What documentation tool did we use?

Sandcastle is the documentation tool used to convert the project xml documentation into the format
you see from this link.  In the future, there may also be a documentation.chm file in the same site that
you can download and it will have better search capabilities.

Why is the documentation so lame?

ReSharper was used to auto generate most of the inline documentation, because there was none
before.  The quality of these comments will improve as we update existing lame comments or add our
own new comments.

Why did we choose Sandcastle?

There as a few XML generators.  If you want to try another, just check with your manager first and go for
it.

Who is the authority on Sandcastle?

You can be!  There are a couple of good web sites about it too, including: codeplex.com and
google.com.  This is a powerful tool and we have only scratched the surface of what it can do. 

Why only some of the API?

We started StyleCop with the API solution.  Other API projects will be included as style is applied to
them.  Coming Soon - other solutions will be addressed after the api.

Where will this documentation be deployed?

The documentation will only be deployed to the web site listed above.  It will not be deployed to qa or
prod environments.

How often will the web site documentation be updated?

That depends.  The JPayDeploy automated process is not finished yet, and will further wait for a
dedicated development environment (an essential part of the automation).  But when it is available,
documentation could be deployed as much as daily. 
Until then (and coming soon), it will be only be deployed with every manual development deployment
to the dev environment.

What is the deployment cost of this documentation?

Building the documentation from the project output is expensive and takes additional time – we may
need to move the dev cutoff to be earlier to make additional time to build the documentation (until it
can be automated in the middle of the night).  Also, the documentation will add to the size of the
deployment kit, so eventually we may need to figure out how to zip it up.

How do I build the documentation on my computer?

Coming Soon - Sandcastle is part of the jpay repo and we are still working on getting it to work on your
computer without you needing to install additional software. 

What are the steps to add new projects to this documentation?

Is this documentation really as easy as 6 simple steps?  Yes it is.
1) Add StyleCop enforcement to a project – we have a team doing this
2) Set the project properties to generate XML documentation. 
3) Build the project and address any compiler problem – generating documentation will cause the
existing inline documentation to be “compiled”.  At least compiled enough to generate a
compiler warning that should be treated as an error.
4) Open the .shfbproj file in the \documentation folder and add the project.  Use MSBuild on this
file to ensure that it builds well (will be available soon).
5) Check in your changes
6) Coming Soon - Check the documentation site tomorrow for the new classes (or after the next
dev deployment).

Can I save links to documentation pages?

That depends – this capability may not be reliable.  Instead – you can become familiar with the table of
contents so you can find things quickly – at least quicker than opening VS.  For example, Navigate to:
JPayBase, JPayUser, eEmailStatus to see this enumeration and the most excellent description (generated
by ReSharper) of the NotNeeded member.  How great is that!

Updates 4/2/13
Can I save links to documentation pages?
Yes, as it turns out! Use the direct link link about the table of contents while you are on the page you
want to add to your favorites. The pages are created using the namespace rather that a guid. So your
saved links should be fairly descriptive too. HOWEVER, only new and updated documentation is
deployed to the web server (not deletes), so it may be possible that you have a link to an expired
documentation page.

How do I build the documentation on my computer?

So Sorry! You will need to install sandcastle on your computer to build the documentation. Get
sandcastle from the R&D tools folder - SHFBGuidedInstaller_1960.zip
More documentation available
With the bulk StyleCop effort coming to an end, most of the API projects are now included. Don’t
bother looking for the TestBed projects. And the ones that were cookie cutter copied are represented
only once. Adding all these projects did not make the sandcastle build run any quicker though. When
we move to a more powerful build server, it may be able to handle the plugins, web services, and kiosks
projects too.

Documentation is cheaper
Not really, but at least the documentation is zipped so it uses much less space, although it does take a
few more seconds to unzip during deployment.

Updates 5/3/2013
New URL!
The dev web server has moved into the qa domain. The new url is:

http://mirsrvdevweb03.qajpay.com/help

Updates 5/20/2014
Server name has changed. The new url is:
http://mirsrvdevweb01.qajpay.com/help/

Updates 4/22/2015
Many kiosk projects added to Sandcastle – downside is there are new build warnings for now.
SHFB upgrade may be necessary - https://github.com/EWSoftware/SHFB/releases
cc.net JPayDeploy project builds and deploys documentation daily (depending on the miracle of
deployment). The cc.net email notice build number will match the documentation version (only for
classes that are auto versioned)
Updates 2/18/2016
URL has changed to:
http://jpayhelp.dev1.jpay.com/
You are welcome.