Best way to add developer documentation to your Visual Studio projects
Basically, the question is: Where (and in which format) should I store textual developer documentation associated with my Visual Studio projects?
To elaborate: XML comments are great, but they don't cover all use cases. Sometimes, you'd like to describe the class architecture of the project at a high level, add usage notes to your library or just leave any other kind of message to future generations of developers working on this project.
I'd like to add these documents directly as files into the Visual Studio project, to ensure (a) that they are available to the developer without further searching and (b) they are version controlled (using the same svn/git/whatever repository as the source code).
Currently, I add a folder _Documentation to the project and use text files, but I'm not sure if this is the best solution. Visual Studio does not have an option for automatically word-wrapping text1, and manually fixing line breaks after each change is annoying. On the other hand, Word documents don't work well with version control, and TeX is too much of a hassle to set up and teach on each developer PC.
Is there a well-established best practice for this?
1 I know that there's Edit/Advanced/Word-Wrap, but this only affects the display, not the file itself.
Answer
I just had the same issue - only I noticed that I was able to add a HTML-file. Once opened, simply switch to "Design" at the bottom of the screen. You may want to change Build Action from 'Content' to 'None'
As it is a hard-coded HTML document, it is also possible to use inline pictures (e.g. a diagram)
Also for my purpose (programming guide, architecture description. database use examples) I opted to create a separate project (_Documentation) as a Windows Forms, as this will allow me (or a new programmer) to have a running example.