By Edhy Rijo - 6/8/2009
Can anybody recommend a good documentation tool for VB.NET projects?
I am looking for something that helps me out write notes, busines rules explanation, etc for my forms, Business Objects, etc. Currently I am using MS Word to write down all my specs and annotations, but if such a tool exist for .NET that helps out simplify the documentation process per project I would like to start using it.
|
By Peter Jones - 6/8/2009
Hi Edhy,
I would take a good look inside VS itself especially if you are using Team Foundation Server.
There are a number of templates available and the "Work Items List" in TFS is good. Also we also found keeping "README.txt" notes, as needed, within each Project within a Solution quite handy. This has the advantage of being part of source control and the one TFS backup makes sure we have everything present and accounted for.
One thing that we do do that may not seem obvious (it didn't to us at first) is to have Project that contains all our SQL stored procedures and triggers (we don't use the SF DDT). This SQL code becomes very easy to maintain and propergate to our databases and, of source, full version control; change history and a certain daily backup.
Cheers, Peter
|
By Edhy Rijo - 6/8/2009
Hi Peter,
Thanks for the answer, unfortunately I am not using VS Team Foundation Server, but will keep it in mind if I decide to use TFS on the next VS2010.
|
By Greg McGuffey - 6/9/2009
I tend to follow a tactic similar to Peter's. I just use text files, and put them under version control. This allows me easy access and easy diffs. Not pretty though. I tend to use Word (or OpenOffice) if I need to communicate with the customer/business people.
I also like to keep all my SQL scripts under source control, though I don't put them within the solution. As mentioned by Trent in another post, if using the DDT, integrating the creation of a package during the build process, that then gets put under source control is seems like an excellent way to manage this also.
I also tend to just document much of this sort of thing directly in code, using XML comments (/// or '''). This makes the logic available within the object browser and you can use Sandcastle (which I haven't yet) to make msdn help files of your objects. By putting it directly within the code, it is easier to keep track of it, it tends to be were I need it, when I need it.
My system isn't perfect, so I'll be interested in any other ideas of how to manage this sort of documentation myself. 
|
By Edhy Rijo - 6/9/2009
Greg McGuffey (06/09/2009)
I also tend to just document much of this sort of thing directly in code, using XML comments (/// or '''). This makes the logic available within the object browser and you can use Sandcastle (which I haven't yet) to make msdn help files of your objects. By putting it directly within the code, it is easier to keep track of it, it tends to be were I need it, when I need it.
Thanks Greg. currently I am using the XML comments and then have the Obfuscator remove the comments. I am also googling some other documentation tools and will post here if find something interesting that will make our life a bit easier  .
|
By Jason Seidell - 6/9/2009
Yeah, I'm in the same boat, would like Foundation server but can't justify the cost.
We are using Sandcastle to build documentation from the XML files, although we only just started with Sandcastle it seems to work ok until you starting building a large set of related libraries then it seems to take a long time to build all the dependencies and links. We have SourceGear Fortress for revision control which has an included bug/issue tracker. It is ok for identifying issues and then tracking when a code fix was applied against it, but not a very good interface for documentation and team communication about an issue. So we use Sharepoint to make documentation/work orders for code changes, and then in the fortress work item just post a link to Sharepoint. I like how Sharepoint can interface with Outlook, email updates, and provide all users access to see what is going on with work orders (instead of only Fortress users), but I will be the first to admit it is a pain creating Sharepoint documentation, then a Fortress item and linking them together.
On a more high level, finalized project documentation, we are starting to use a wiki page on Sharepoint. It is just as quick as writing out a word document, but I don't have to worry about a 100-page word document, updating a table of contents, and how to link together related information in seperate documents. Sharepoint also works nice because I can do a search and find items without the pain of trying to do windows searches through text files.
|
|