Do The NDoc Rock!
Anybody who's ever read some of my rants on eggheadcafe.com knows that I am a big proponent of writing documentation for your creations WHILE YOU ARE CREATING. The reasoning for this should be as objective as gravity to anybody who has walked into a new environment and had code thrown at them for which there is ZERO documentation (Sound familiar?).
I wrote a "HOWTO" article recently just to show how easy it is to document your C# classes, then use NDoc and the HTML Help Compiler to create beautiful MSDN style CHM help files with TOC, index and fulltext search (Beats those crappy PDF's by a mile!).
Recently I had to do this again with a solution that I and another dev are working on which has about 21 different class libraries in it. Of those, 75% or more had NO DOCUMENTATION at all. What's worse, a few of the C# ones actually had old "//" style comments but the guys put them in using old C-style double-slashes instead of the built-in triple slash "///<summary... >" tag structure.
I can't stress this enough: If you want to be a professional developer, you must learn to write and create professional documentation AS AN INTEGRAL PART OF EACH OF YOUR PROJECTS.
It cannot be an "afterthought". It must be part of your deliverable! Unless you are totally coddled, you do not work in a vacuum. Other people will need to look at your code. In fact, six months from now, YOU may need to revisit your code.
Enough said. NDoc 1.3.1 now has a very nice new Alpha feature as a new output option called "Linear HTML" -- which essentially puts all your C# documentation into a single HTML file complete with CSS and internal anchor-style hyperlinks. You can save this as MHT, or you can even pull it into MS Word and save it back out as a Word document (some organizations are stupid enough to require Word documentation instead of Full-text searchable CHM). That's in addition to the HTML version, which creates online website of your help that looks and acts almost identical to MSDN online (including that nice "Sync TOC" link), as well as MSDN "CHM", Visual Studio HTML Help 2.0 format, and several other cross-platform choices.
But it all starts at one place - while you are writing the code, with XML comment tags, which you must learn to use correctly.
I wrote a "HOWTO" article recently just to show how easy it is to document your C# classes, then use NDoc and the HTML Help Compiler to create beautiful MSDN style CHM help files with TOC, index and fulltext search (Beats those crappy PDF's by a mile!).
Recently I had to do this again with a solution that I and another dev are working on which has about 21 different class libraries in it. Of those, 75% or more had NO DOCUMENTATION at all. What's worse, a few of the C# ones actually had old "//" style comments but the guys put them in using old C-style double-slashes instead of the built-in triple slash "///<summary... >" tag structure.
I can't stress this enough: If you want to be a professional developer, you must learn to write and create professional documentation AS AN INTEGRAL PART OF EACH OF YOUR PROJECTS.
It cannot be an "afterthought". It must be part of your deliverable! Unless you are totally coddled, you do not work in a vacuum. Other people will need to look at your code. In fact, six months from now, YOU may need to revisit your code.
Enough said. NDoc 1.3.1 now has a very nice new Alpha feature as a new output option called "Linear HTML" -- which essentially puts all your C# documentation into a single HTML file complete with CSS and internal anchor-style hyperlinks. You can save this as MHT, or you can even pull it into MS Word and save it back out as a Word document (some organizations are stupid enough to require Word documentation instead of Full-text searchable CHM). That's in addition to the HTML version, which creates online website of your help that looks and acts almost identical to MSDN online (including that nice "Sync TOC" link), as well as MSDN "CHM", Visual Studio HTML Help 2.0 format, and several other cross-platform choices.
But it all starts at one place - while you are writing the code, with XML comment tags, which you must learn to use correctly.
Comments
Post a Comment