what user help formats are recommended?

[jen]

i'm trying to decide what format to use when it comes to building user
help and tips.

..chm files, tooltips, custom forms, other...? is there a tool that
"easily" lets you build
help files (.chm, etc..)?

what else is out there?

thanks to those who reply...i appreciate the input!

 

[Marina Levit [MVP]]

If you type in three apostrophes in a row above a class or class member,
etc. VS will default some XML documentation comment tags. Fill in the tags,
compile, and this will provide intellisense when you use the assembly
elsewhere.

As for documentation, the only thing I am aware of that is free and produces
documentation is NDoc. You can google for it. It is capable of creating
HTML files and CHM files which look pretty nice. The only weird thing is,
for 2005, you need to download the source for NDoc, compile it, and then run
the executable. The executable off their download site doesn't actually work
and ends up throwing exceptions.

 

[jen]

thanks marina, i'm actually using NDoc for developer documentaion at
this point (how to use the class libraries (.ddl)). i structure our
code with the XML notation you speak of (/// for c#). but building user
type documentation (how to use the product), is a different story.

by the way, i am able to use the NDoc executable, but i had to add the
following to a NDocGui.exe.config file, which is parallel to the NDoc
executable...where the version is set to whatever you have.

<configuration>
<startup>
<supportedRuntime version="v2.0.50727" />
</startup>
</configuration>

-
jen

 

[V]

You might want to check out SandCastle. It is the code-name for a tool
that Microsoft used internally to develop documentation for Visual
Studio 2005, I believe. (Basically MSDN style). However, having said
that, I felt that the kind of documentation capabilities that
SandCastle is offering are more suited to documenting API type products
as compared to Help Manuals.

Also, what kind of app are you trying to provide help for (web or
windows)?

Also take a look at RoboHelp product.

Regards,
V

 

[Dave Sexton]

Hi Jen,


The Html Help tools will allow you to make your own .chm file that has nothing
to do with xml code comments:

"Microsoft Html Help Downloads"
http://msdn.microsoft.com/library/d...tmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp

Use the HelpProvider component on your Forms and dialogs to provide
context-sensitive help:

"HelpProvider Component Overview"
http://msdn2.microsoft.com/en-us/library/s3ztx0at(VS.80).aspx

You can supply context-sensitive help in your application's dialogs using the
Form.HelpButton property, which adds a "?" button to the title bar.
In non-dialog Forms you can add your own Button that displays the standard "?"
image, or anything you'd like, next to items that have help available.

I recommend using the ToolTip class as well. End-users appreciate quick,
unobtrusive, helpful messages whenever possible.

As for displaying help in custom forms, I'm not against it, but I'd question
whether custom help forms could provide any value that .chm, HelpButton and
ToolTip doesn't already provide.

 

[Laurent Bugnion]

Hi,

You might want to check out SandCastle. It is the code-name for a tool
that Microsoft used internally to develop documentation for Visual
Studio 2005, I believe. (Basically MSDN style). However, having said
that, I felt that the kind of documentation capabilities that
SandCastle is offering are more suited to documenting API type products
as compared to Help Manuals.

Also, what kind of app are you trying to provide help for (web or
windows)?

Also take a look at RoboHelp product.

Regards,
V

Added to that, you don't want to use Sandcastle without the Sandcastle
Help builder
http://www.codeproject.com/useritems/SandcastleBuilder.asp

Also, you're right, it's more to document APIs than to build end-user
documentation. In that sense, Sandcastle is the direct
successor/replacement of NDoc.

HTH,
Laurent

 

[Marina Levit [MVP]]

I was dissapointed to find out this was just a set of command line tools.
At that point, it is easier to use NDoc. Not sure why they didn't bother
building a front end for it - would make it a ton more useful. To me, it's
just not worth fumbling around with the command line stuff to get it just
right so all my DLLs are included, etc.

You might want to check out SandCastle. It is the code-name for a tool
that Microsoft used internally to develop documentation for Visual
Studio 2005, I believe. (Basically MSDN style). However, having said
that, I felt that the kind of documentation capabilities that
SandCastle is offering are more suited to documenting API type products
as compared to Help Manuals.

Also, what kind of app are you trying to provide help for (web or
windows)?

Also take a look at RoboHelp product.

Regards,
V

thanks marina, i'm actually using NDoc for developer documentaion at
this point (how to use the class libraries (.ddl)). i structure our
code with the XML notation you speak of (/// for c#). but building user
type documentation (how to use the product), is a different story.

by the way, i am able to use the NDoc executable, but i had to add the
following to a NDocGui.exe.config file, which is parallel to the NDoc
executable...where the version is set to whatever you have.

<configuration>
<startup>
<supportedRuntime version="v2.0.50727" />
</startup>
</configuration>

-
jen

If you type in three apostrophes in a row above a class or class
member,
etc. VS will default some XML documentation comment tags. Fill in the
tags,
compile, and this will provide intellisense when you use the assembly
elsewhere.

As for documentation, the only thing I am aware of that is free and
produces
documentation is NDoc. You can google for it. It is capable of
creating
HTML files and CHM files which look pretty nice. The only weird thing
is,
for 2005, you need to download the source for NDoc, compile it, and
then run
the executable. The executable off their download site doesn't actually
work
and ends up throwing exceptions.

i'm trying to decide what format to use when it comes to building
user
help and tips.

.chm files, tooltips, custom forms, other...? is there a tool that
"easily" lets you build
help files (.chm, etc..)?

what else is out there?

thanks to those who reply...i appreciate the input!

 

[Laurent Bugnion]

Hi,

I was dissapointed to find out this was just a set of command line tools.
At that point, it is easier to use NDoc. Not sure why they didn't bother
building a front end for it - would make it a ton more useful. To me, it's
just not worth fumbling around with the command line stuff to get it just
right so all my DLLs are included, etc.

As I said,
http://www.codeproject.com/useritems/SandcastleBuilder.asp



Laurent

 

[V]

I was not aware of the SandCastleBuilder... will be trying it out. Been
using the command line tools, calling them from a custom auto-builder
that I wrote for continuous integration.

Thanks for the link.

Regards,
Vaibhav