47

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.

Heinzi
  • 167,459
  • 57
  • 363
  • 519
  • Check if [http://stackoverflow.com/questions/7820013/insert-image-in-code-cs-file][1] helps you. [1]: http://stackoverflow.com/questions/7820013/insert-image-in-code-cs-file – Ram Mar 16 '12 at 10:49
  • I have the exact same workflow (and thus problem :). Did you find any way yet to solve this? I'm thinking on writing a visual studio extension for this purpose, I would love some hands on information! – MHGameWork Sep 16 '13 at 09:02
  • @MHGameWork: Not yet, we are currently still using simple text files added to the solution. Fortunately, not much high-level documentation is required at the moment. – Heinzi Sep 16 '13 at 09:13
  • Ok, thanks for the update! If you should find something, I would be really interested to hear about it :) – MHGameWork Sep 17 '13 at 13:01
  • @MHGameWork: I started to use the [rewrap extension](https://marketplace.visualstudio.com/items?itemName=stkb.Rewrap-18980) to easily format my code comments. Coincidentally, this also solved my documentation problem: I can simply use text files and re-wrap paragraphs with Alt-q. – Heinzi Mar 10 '22 at 09:11
  • Hooray, Visual Studio [gets a built-in Markdown editor](https://devblogs.microsoft.com/visualstudio/write-markdown-without-leaving-visual-studio/)! – Heinzi Dec 25 '22 at 10:25

4 Answers4

8

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.

shA.t
  • 16,580
  • 5
  • 54
  • 111
aliceraunsbaek
  • 625
  • 7
  • 18
  • If you can't find the "Design" mode for html files, see this answer: http://stackoverflow.com/a/31655106/1701463 – MikeH Mar 09 '17 at 22:31
3

I use GhostDoc (visual studio add-on) for documentation of my project as I add classes, methods, properties etc: http://visualstudiogallery.msdn.microsoft.com/46A20578-F0D5-4B1E-B55D-F001A6345748

ianaldo21
  • 679
  • 4
  • 10
  • 3
    XML comments are great for specific items (classes, methods, etc) - how to include *overall* or *architecture* documentation? – user2864740 Dec 30 '14 at 19:58
2

You have the option, in XML comments, to include a lot of data that you can then pick up with a tool like Sandcastle (site) and turn into an actual MSDN-style reference site.

I tend to use this method and just write long XML comments (MSDN comment tags) (where appropriate) using the <para></para> to generate paragraphs and explain any patterns, business reasons or architectural information necessary to future modifiers/developers. I also use it to give usage examples.

A good batch of tests (well written and named) can also really illuminate the purpose of code, acting as a spec.

I hope that might be a little informative in your research :)

  • 4
    XML comments are great for specific items (classes, methods, etc) - how to include *overall* or *architecture* documentation? – user2864740 Dec 30 '14 at 19:58
0

XML Comments is best for documenting the particular method and not ideal for writing long conceptual content. Long XML comments could adversely affect code readability.

I liked Conceptual topic documentation feature of Sandcastle, we can create and store Conceptual documentation whether functional or architecture related and merge it with Code documentation (XML Comments). Markups which you can use in writing the conceptual topics are extendable which means we can even adhere to Enterprise templates.

ideafountain
  • 575
  • 5
  • 17