[Choscura]

I'm working on a big project (relative term: couple thousand lines of code so far, probably 3-4 times this much before anything is ready to be released) across a few different languages (right now, C# and python), and I'm curious how people here keep track of documentation. I've been keeping stuff in a notepad document, but it's getting a bit too big for that, and I was hoping somebody here would be able to recommend something perhaps more useful than a wiki?

[Kilorn]

I usually use Microsoft Word if it's a solo project, or Google Docs for team projects.

[SpartanGuy07]

For my work I use LaTeX, however my position is specifically the technical writer for the project and it does take some getting used to. It does create very nice PDFs though.

[tlhIn`toq]

I like documentation that goes with the class/project/solution.

Extensive use of in-code comments. Decently named objects/methods/variables/properties.

private ResultsObject SomeMethod(string blah)
{
   // Step 1.  We do blah blah blah
   // Step 2.  We invert those results
   // Step 3.  We filter those results
   // Step 4.  We return results as "halb (3 times)"

   #region Step 1
   {
   }
   #endregion Step 1
}

XML comments on every method and property so intellisense works for everyone. (/// comments at each method)

    /// <summary>No GUI code here.  This is an object to work the camera device, not directly interact with the user
    /// 
    /// </summary>
    public class CameraGoPro : CameraBase
    {


        /// <summary>NO EFFECT: Inherited from CameraBase, but no such property in THIS camera model.
        /// </summary>
        [Browsable(false)]
        [EditorBrowsable(EditorBrowsableState.Never)]
        [XmlIgnore]
        public new string ISO
        {

        /// <summary>The CurrentUser's AppData directory. 
        /// We always have security permissions for this and is the preferred location for storing Application specific data
        /// </summary>
        public static string AppData
        {

and txt documents in each project or subfolder.

I'm not sure why you would use Notepad and documents elsewhere, when you can create a textfile IN the project and use VS to write it: In the very folder it applies to. There is no chance of documenation getting separated from the project if you use the tools built in to the IDE. If I write a custom control for example, there is a text document in the folder that describes its theory of operation as well as a ChangeLog.txt file.

This post has been edited by tlhIn`toq: 14 March 2012 - 12:42 PM

[anonymouscodder]

Doxygen

This post has been edited by anonymouscodder: 14 March 2012 - 12:48 PM

[Curtis Rutland]

If you're using C#, use the XML comments, and use Doxygen. Doxygen will read the xml comments and generate a javadoc-style webpage for you, which is awesome.

[calvinthedestroyer]

We use "share point" at work.
All the documents start off in MS ACCESS. Once the document gets approved it shows up in share point with a nice digital signature.

I don't like it, it does not allow for multi users. I constantly run into issues where I can't edit a doc because some one else left it open.
Half the time you don't have the right permissions to make changes.
And the MS ACCESS Gods are old and always on vacation.

[Core]

Really don't think code comments is where documentation should go. Clutters the space a lot. For most of my projects (hosted either on CodePlex or GitHub) I am using the integrated Wiki system.

[jon.kiparsky]

Depends what it is you're trying to document. Doxygen is a great tool. I've got a thing I've been playing with (mentioned it in a recent thread) where I use svn hoooks to tell doxygen to regenerate its documentation, so the autogen docs are always current. It's a little tricky, since there's a ton of projects in a ton of languages in the work repo, but fortunately they're mostly categorized by language, so it's not too hard. If you've got multiple projects in one repo, you need to make sure you're not generating documentation for all of them each time, that would be a nuisance.


For design documents, an authoring tool like Oxygen is handy. Oxygen is a DocBook editor, so it's easy to generate html and PDF from the same document - this keeps your documentation versions constant. Also, it's plain text, so it plays nice with svn. (keep the docs in the repo, for the same reason you eep the code in the repo). Oxygen is not a free product, either as speech or beer, but it's reasonably cheap and well supported. I understand that eclipse can be used as a DocBook editor as well, but I haven't done anything with that.
The down side of DocBook is that it takes some work to make it look good. If that's important, use something else or get Bob Stayton's book on DocBook XSL and be ready to spend some time at it.


For user-facing documentation, a DocBook tool is again handy, but you could use something like OpenOffice if you'd rather.

For developer-facing docs, just make your commits self-documenting. Always work from a bug list, and tie every commit to a bug and log the revision that fixes the bug in the bug report. If I'm trying to work out why a piece of code was added, it really helps to see the bug that motivated it. Make your changes small and incremental, and the commit history will tell the story better than a lot of text.

calvinthedestroyer, on 14 March 2012 - 06:47 PM, said:

We use "share point" at work.

That's just horrible. I'm sorry to hear it.

[Raynes]

Some languages like Clojure and Python have a concept of 'docstrings' which are strings of documentation attached to functions and such. Those are a big part of my documentation cycle. When in the mood, I tend to write code in a half-assed literate programming style. I'm not a big fan of full on three-chapters-per-block-of-code literate programming, but I like a paragraph here and there to complement pieces of code and explain why they exist and what part they play. For the literate part of things, Marginalia is an excellent Clojure tool. For API reference documentation which tends to make use of docstrings rather than comments, codox or autodoc are excellent tools.

[Curtis Rutland]

C# has the same thing. Start a comment above a method/class/interface/etc...with three slashes, and it'll generate a set of (commented out) xml, that attaches documentation to your components. That's actually how IntelliSense works when it shows descriptions of classes/methods.

[tlhIn`toq]

See post #4 above, where I posted an example of the /// XML comments.