TIGSource Forums

When you click the "Help" menu item to figure something out/get started with an app, what do you hope you are going to see that first time?

For offline for non-games: PDFs, because they are portable (not like .chms), can be easily sent to other people (not like a bunch of html pages with csses and images and whatever) and have a search function, hyperlinks and copy-to-clipboard (not like most in-app helps). But I generally prefer online help (HTML, no PDFs) for anything.

Liosan

PDF offline + docs/wiki/API ref online.

HTML.

PS you are greating a false dichotomy by specifying the html as online.

PDF for tools / tutorials / walkthroughs, HTML for APIs / libraries.

 :panda:

I was specifically referring to it taking you online to a web page, since it seems to be a pretty common method. With "other" being a viable choice, I'm having trouble understanding why it is a false dichotomy. Can you explain more?

Thanks to you and to everyone for your input thus far :)

PS And are you voting for offline html versus online html then? If so, why?

Offline HTML. It's very important to still be able to read my manual if I'm somewhere without an internet connection, like say an airplane (I went through the entirety of Inkscape's included tutorials during a flight once, and it was awesome). I also don't trust online help to stay online forever, and would generally expect it to change with updates to the program, which I might not want if I'm still on a previous version.

PDF's a good option too, but HTML is easier to read and navigate.

definitely offline html, so you don't need to be online to read it and it's easier/more reliable than pdf.

Precisely.

I prefer offline to online html, and both to your other options. But how you've set the survey up, some people are going to vote PDF over online html, even though offline html is their actual highest choice.

offline html

for the same reasons as ThemsAllTook

Both online and offline HTML. It's easier to me to access something like yourengine.com/doc rather than opening all neccessary folders  :wtf:

Althrough, only offline HTML would do too.

Online is often googlable, which is another reason I would expect the docs to be online/offline.

Good point, yeah. Ideally both online and offline, with the offline version including a link to the online one in case there are corrections or improvements.

Thank you everyone for your input. Your thoughts and opinions and have been very helpful.

 :coffee:

Hmmm.

So does anyone know off the top of their head a good html template or software for creating basic html help? It should at least support a pane on the left with contents and the main view on the right.

I'm not getting very far googling - aside from a couple rather expensive programs.

another for offline html

I like chm's but IIRC they are a windows thing. If you are using Doxygen or a documentation generator then may as well. If it takes any more effort than clicking a checkbox then I wouldnt bother.

Doxygen is great ;)

 ;) I'm looking to document software rather than code. As far as I know doxygen isn't really made for that, is it?

I thought that you meant code... If you want to document "software" then you can use pretty much anything. Any text editor...

or Tex if your feeling ambitious,and maybe need some math symbols and want it proper

I guess what I'm asking is if there is any good, known software for creating documentation in html format. Definitely want something that will create a table of contents on the left, in say a tree view, and search functionality would be nice as well.

If working with chm or pdf this is straightforward, but I'm not exactly sure the best method to go about this in html, and I assumed there was some software or web-template or something that people generally use for this sort of thing.

Any wiki software will work ;)

I also use doxygen. It lets you write actual pages as well as annotating APIs. And it autogenerates hyperlinks to the classes you are talking about, can generate pdfs & tex as well as html, and has tables of contents. It doesn't have any built in search facility though, but you can use google site:mydomain.com for that.

I prefer my help pages to be Google searchable, with lots of hyperlinks between related concepts. The Unity Class hierarchy page is a good example:
http://docs.unity3d.com/Documentation/ScriptReference/20_class_hierarchy.html (http://docs.unity3d.com/Documentation/ScriptReference/20_class_hierarchy.html)

oh wow , didn't know you could export tex, i'll have a look at taht

If I have to turn on my interbutt to read your games manual, and it's an offline game, I'm going to kick your ass.

So offline html it is!

In my experience, help manuals are harder to read than just smashing buttons on the interface.

Would go with html, because you can just pop it into google.

PDF is actually really hard to read on a computer, only good for printed documents and short things like resumes. Would rather just read plaintext.

Don't like CHM. It's actually the best of those choices, but feels dirty.