Do you want to include the following file or folder?

Topics: General Questions
Apr 15, 2010 at 3:02 PM

All --

Please help.
 
When building a DocProject, I get a prompt asking...

"
Do you want to include the following file or folder as a N project item?

bing\Debug\DocProject1.HxS

"
...I have been choosing ApplyToAll=Checked and DontAskMeThisAgain=Checked...

...so is that choosing OK and the right thing to do, in general?

Please advise.

Thank you.

-- Mark Kamoski

Apr 15, 2010 at 4:55 PM
Edited Apr 15, 2010 at 4:56 PM

Hi Mark,

If your project is under source control then no, you probably don't want build output being included in the project.

If your project is not under source control, then it depends upon whether you find it useful to have various build output included in the project.

- Dave

Apr 16, 2010 at 1:21 PM
davedev wrote:

If your project is under source control then no, you probably don't want build output being included in the project.

Davd --

OK, that makes sense, in the general case.

However, what about the following case, where our main goal is to document APIs in the most simple way possibly.

For us, there is no way for us to mandare the creation of a help file for a project.

Furthermore, we do not have enough people to delegate the task of managing all help files for all projects to a single person.

As such, we have sporadic buy-in from developers.

Our "policy" is an "opt-in-per-project" policy, where the lead developer on a given project decides if he or she wants to create and manage a help file for that project.

Given all that, it seems that should do either 1 or 2 below.

1. Create stand-alone CHMs on a per-project basis, check them into source control, and combine them with a tool like ABC Amber CHM Merger http://www.processtext.com/abcchmmerger.html or similar, like maybe DocProject.

    (The main upside here is that we can search across all projects. The main downside is that we do need a source control get-latest operation to get help.)

2. Create a link in each project's readme pointing to an internally hosted DocSite on the machine of the given project's lead developer.

     (The main downside here is that we cannot search across all projects. The main upside is that we do not need a source control get-latest operation to get help.)

(I tend to prefer 2, given that its upside is more important than its downside.)

(I expect that I could "script the whole thing and run it at system start or EOD" but that is a big task that I do not have time for now-- furthermore, it is better, I think, to promote well-rounded team members by having each do his or her own work, and it distributes the overall workload.)

What do you think?

Please advise.

Thank you.

-- Mark Kamoski

Apr 16, 2010 at 5:33 PM
Edited Apr 16, 2010 at 5:34 PM

Hi Mark,

> 1. Create stand-alone CHMs on a per-project basis, check them into source control, and combine them with a tool like ABC Amber CHM Merger [snip]

I don't recommend checking build output into source control.  If you can, set up a Continuous Integration build server instead to have your docs built whenever code is checked in.  You can write an MSBuild script that merges all CHM files found in a drop location that you specify.  The script can also copy the merged CHM file to an internal or external web server, for example.

I've used Team Foundation Server and also TeamCity.  I highly recommend either of those.  TeamCity has a really great free version as well.

2. Create a link in each project's readme pointing to an internally hosted DocSite on the machine of the given project's lead developer.  [snip]

This isn't a collaborative solution.  It will be hard to maintain the documentation and enforce any standards.  You'll probably get varying results from each dev.

Option #3:

Create a single DocSite and host it internally on a web server.  Set up a Continuous Integration (CI) build server and have it rebuild and deploy the DocSite every night so that the documentation will be fresh and up-to-date every morning.  (The DocSite must be in source control, so create a separate solution that all lead devs have access to; more on this below.)

Configure the DocSite to include documentation for all of the projects in your organization.  To do this, your CI server should automatically build a project whenever its code is checked in, and then drop the assemblies and XML documentation files that it produces into a common drop location on the server.  Do this for all of your organization's projects.  Add an External source to your DocSite that points to the drop location and picks up all assemblies and XML documentation files; e.g., specify the drop directory as a path with a recursive wildcard in the External sources dialog for both the assembly and XML documentation columns.

For new projects, the lead dev simply needs to check out the DocSite and update the table of contents to create any conceptual documentation they might want for their project.  If they only want to include reference documentation then no action is required.

- Dave

Apr 16, 2010 at 6:29 PM
Edited Apr 16, 2010 at 7:57 PM
davedev wrote:

...Option #3: Create a single DocSite and host it internally on a web server.  Set up a Continuous Integration (CI) build server and have it rebuild and deploy the DocSite every night so that the documentation will be fresh...

Right-O.

We had a brainstorm and came up with this same solution except for CI we thought we would use dirt-simple BAT scripts.

For "real" CI, it has been a while, but I thought CruiseControl was the freware "standard" but maybe TeamCity is better?

Hmmm.

My only hesitation here is that I end up doing all the process-research, process-design, process-implemenation, process-management, etc. I know that if it is setup correctly, it can be near-touchless. However, there is an initial investment of time. Furthermore, sometimes such process takes on a life of its own.

I accept the "best practices" angle-- you are right and I agree.

However, I need a Yagni-driven, Gefn-driven process first, I think.

If we keep the work-done on a "opt-in per project" basis, then we can distribute the workload.

Thoughts?

-- Mark Kamoski

Apr 21, 2010 at 5:02 PM

Hi Mark,

I understand your situation, though you'll probably save lots of time in the long run by committing some extra time now to set up a stable build environment for your organization.

Note that my solution above can actually be "opt-in per project" as well.  Just leave it up to each lead dev whether or not they want to include their assemblies as documentation sources in the global DocSite that I had mentioned.  It's really not a CI issue because using batch files still means that either manually or automatically the assemblies to be documented need to end up in the proper location so they may be included by the DocSite.

One more thing: I highly recommend using MSBuild instead of batch scripts.  There's certainly a learning curve though.  It will take you significantly more time to write your first few scripts in MSBuild if you don't have any experience with it; however, it's definitely worth learning ASAP.  As soon as you get the hang of it, you'll be able to write scripts much faster and that are much clearer and easier to maintain using MSBuild than with batch files.

- Dave