Back in the old days, Help was not trivial but possible: generate some funky .rtf file with special tags, run it through a compiler, and you got a WinHelp file (.hlp) that actually works really well.
Then, Microsoft decided that WinHelp was not hip and cool anymore and switched to CHM, up to the point they actually axed WinHelp from Vista.
Now, CHM maybe nice, but everyone that tried to open a .chm file on the Network will know the nice "Navigation to the webpage was canceled" screen that is caused by security restrictions.
While there are ways to make CHM work off the network, this is hardly a good choice, because when a user presses the Help Button he wants help and not have to make some funky settings
Bottom Line: I find CHM absolutely unusable. But with WinHelp not being an option anymore either, I wonder what the alternatives are, especially when it comes to integrate with my Application (i.e. for WinHelp and CHM there are functions that allow you to directly jump to a topic)?
PDF has the disadvantage of requiring the Adobe Reader (or one of the more lightweight ones that not many people use). I could live with that seeing as this is kind of standard nowadays, but can you tell it reliably to jump to a given page/anchor?
HTML files seem to be the best choice, you then just have to deal with different browsers (CSS and stuff).
Edit: I am looking to create my own Help Files. As I am a fan of the "No Setup, Just Extract and Run" Philosophy, i had that problem many times in the past because many of my users will run it off the network, which causes exactly this problem.
So i am looking for a more robust and future-proof way to provide help to my users without having to code a different help system for each application i make.
CHM is a really nice format, but that Security Stuff makes it unusable, as a Help system is supposed to provide help to the user, not to generate even more problems.
Yep, at some point they want to add behaviour to their help files which makes it a security issue and guess what happens, the remedy being often worse than the threat.
Or it's too simple or too complicated and being replaced by something new without caring for backward compatibility.
If you want it really simple and build for the ages go for .TXT
You didn't specify what your apps are coded in so it depends.
If it's a web app, plain HTML would be the best choice, for a help file you don't need special features or javascript so being browser independant should be straightforward. But also for desktop apps HTML, on- or offline are often used with good results.
PDF is the other general solution, and yes you can jump to specific pages, see this answer. Every pc has (or should) one client or the other installed, I wouldn't worry about that. I myself never choose Acrobat Reader, faster, sompler and often better solutions are available, my favorite is Sumatra.
I'm sure .Net apps have their own help system (no experience here) and many languages have options to display tooltips, windows or pages with help either by pressing a hotkey (F1) or clicking some control dialog.
Related
I recently installed a Firefox extension and noticed that it was doing something very odd in the background.
I'm a web developer and use Wordpress mainly. One day I was working on a page in WP admin and switched to the Text rather than Visual mode so I could edit some HTML. I noticed a load of junk html in there hidden using display:none
The class names rang a bell, it was the name of the extension I had installed several weeks previous
I immediately uninstalled the extension but of course it was too late. Since it was injecting code right into the text entry boxes in Wordpress, all that junk got saved with my pages. I had to weed through dozens and manually delete this junk, which in some cases had affected the layout.
I contacted the developers, and they gave me some rubbish about it being totally normal, everyone does this sort of thing, its within the Mozilla dev terms, and that it was a feature not a horrific Malware as I was putting forward.
In this case it was just html/css, but what if they were injecting JS/php etc, they could be causing all kinds of damage
I just wondered from a development perspective what peoples thoughts were. Is this legal?
Many thanks in advance
The best course of action is to spread awareness. I would not do here, but maybe write a detailed article explaining which extension it is, what it does, how, why it's bad, how to get rid of it, and alternatives.
Medium, your own blog, Hacker News and other social outlets will certainly be welcoming of such informations. The developers are very well aware of what they are doing so don't expect them to broadcast it and/or take action.
Be also sure to read their ToS again, see what you agreed to. If something seems suspicious you can talk to a lawyer or probably report them, altough this is beyond what I know.
I am a Mozilla Addon reviewer. Please report your findings as Abuse report and/or addon review (it will be read).
I have tried almost every IDE listed here, but none of them provide code completion.
As a Flex developer I am used to code completion in Flash Builder. It saves tons of time and helps with spelling errors.
Does anybody know about IDE with code completion for Cappuccino? Is is difficult to create, or it is simply not as important for everybody as it is important for me?
Our company is gonna use Cappuccino heavily, and thus I don't mind to ask one developer to volunteer and create some kind of Eclipse plugin. Just let me know, how important it is and how difficult it would be.
There's no full IDE support that I know of, but several text editors have support. Coda ships with it, and there exist textmate and sublime text plugins (Several of the core team members use Sublime, and I hear it's pretty good.) https://github.com/aparajita/Cappuccino-Sublime
Also, unfortunately, the website is a pretty poor resource for finding relevant content, it works for some old stuff that hasn't changed (like the tutorials), but things like debugging and editors the info is almost certainly out of date because of how rapidly these things are changing.
For some time I've noticed how much the File Open and File save dialogs vary between Windows itself and Applications. In Delphi for example (which I use) you can use the built-in dialogs (which have a folder tree) and direct calls to the Windows API which produce variants of the Windows version, with or without large buttons for 'Desktop', 'My Computer' etc (At least on XP).
As an application developer I'm interested in providing the User with a clean, simple way of loading and saving files. Typically, this requires that I propose a preferred folder where my Application data files are stored but that I allow the User to access other folders - often the desktop and other local drives, and sometimes the network - without difficulty if required.
With the introduction of Vista, we seem to be favouring a 'bits missing' folder navigation tree for Windows dialogs and now, Windows 7 has another 'line-less tree' for navigation. I suspect that if one conforms to Microsofts assumptions and stores everything in ~/documents it's not a big problem. However, if one has to start at the root of a drives tree and there are many directories then it's a right pain - there is no horizontal scrolling so directory names get truncated.
My question is - what do other Application developers use? I wonder whether I should be following this Windows lead or simply sticking to a simple cut-down version of File dialogs over which I full control but risk falling into the past....?
Thanks
Brian
Always use the OS defaults - it'll be what your users are used to, and what they expect. Whatever you do, don't astonish the user. Whatever you do, please don't write your own file-open/file-save dialog.
FWIW, I'm not a great fan of Vista's file-open dialog (why do I have to work so hard to navigate my folders?), but I'd rather that than have to get to grips with something new. The less things your users have to learn, the easier your product is to use.
Since I am currently only coding for customers with Windows XP (in a corporate environment that isn't upgrading just yet) I use the standard dialog boxes.
When we do upgrade, I will most likely continue to use the standard old fashioned dialog boxes, until our customers are ready for a change.
In all honesty, I involve at least a few users in the development process, and I won't start new features unless I can bring one in to sit in front of my development PC to see how it works, and they sign off on it.
For those apps that we write for our web site, we tend to be conservative as well... Focus on clean, understandable design, and introduce fancy new features only when there is a compelling reason, and even then, we tend to involve focus groups.
So all that was a long way of saying "Ask your customers". Give them what they want.
Is it worth to try to keep your GUI within the system looks ?
Every major program have their own anyways...
(visual studio, iexplorer, firefox, symantec utilities, adobe ...)
Or just the frame and dialogs should be left in the system look 'n feel range ?
update:
One easy exemple, if you want to add a close button to your tab, usually you make it against your current desktop theme. But if the user has a different theme, your close button is out of place, it doesn't fit the system look anymore.
I played with the uxtheme api, but there is nothing much you can do, and some themes i've seen are incomplete sets.
So to address this issue, the best way i see, is to do like visual studio/firefox/chrome roolup your own tab control with your theme...
I think, that unless your program becomes a very major part of the users life, you should strive to minimize "surprises" and maximimze recognizability (is that even a word?).
So, if you are making something that is used by 1.000 people for 10 minutes a day, go with system looks, and mechanisms.
If, on the other hand, you are making something that 100 people are using for 6 hours a day, I would start exploring what UI improvements and shortcuts I could cram in to make those 6 hours easier to deal with.
Notice however, that UI fixes must not come at the expense of performance. This is almost always the case in the beginning when someone thinks that simply overriding the OnPaint event in .Net will be sufficient.
Before you know it you are once again intercepting NC_PAINT and NC_BACKGROUNDERASE and all those little tricks to make it go as fast as the built-in controls.
I tend to agree with others here- especially Soraz and Smaci.
One thing I'll add, though. If you do feel that the OS L&F is too constraining, and you have good grounds for going beyond it, I'd strive to follow the priciple of "Pacing and leading" (which I'm borrowing here from an NLP context).
The idea is that you still want to capitalise as much as possible on your intended audidences familiarity with the host OS (there will be rare exceptions to this, as Smaci has already covered). So you use as much as possible of the "standard" controls and behaviours (this is the "pacing") - but extend it where necessary in ways that still "fit in" as much as possible (leading).
You've already mentioned some good examples of this principle at work - Visual Studio, even Office to some extend (Office is "special" as new UI styles that cut their teeth here often find their way back into future OS versions - or de-facto standards).
I'm bringing this up to contrast the type of apps that just "do it their way" - usually because they've been ported from another platform, or have been written to be cross-platform in GUI as well as core. Java apps often fall into this category, but they're not the only ones. It's not as bad as it used to be, but even today most pro audio apps have mongrel UIs, showing their lineage as they have been ported from one platform to another through the years. While there might be good business reasons for these examples, it remains that their UIs tend to suck and going this route should be avoided if in any way possible!
The overriding principle is still to follow the path of least surprise, and take account of your user's familiarity with the OS, and ratio of their time using your app to others on the OS.
Yes, if only because it enables the OS to use any accessability features that are built in like text-to-speech. There is nothing more annoying for someone who needs accessability features to have yet another UI that breaks all the tools they are used to.
I'd say it depends on the users, the application and the platform. The interface should be intuitive to the users, which is only the same as following system UI standards if they are appropriate for those users. For example, in the past I have been involved in developing hand held systems for dairy and bread delivery on Windows CE hand helds. The users in this case typically were not computer literate, and had a weak educational backround. The user interface focussed on ease of use through simple language and was modelled on a pre-existing paper form system. It made no attempt to follow the Windows look and feel as this would not have been appropriate.
Currently, I develop very graphical software for a user group that is typically 3rd level educated and very computer literate. The expectation here is that the software will adhere to and extend the Windows look and feel.
Software should be easy and intuitive where possible, and how to achieve this is entirely context dependent.
I'd like to reply with another question (Not really Stackoverflow protocol, but I think that, in this case, it's justified)
The question is 'Is it worth breaking the OS look and feel?'
In other words,
Do you have justification for doing so? (In order to present data in some way that's not possible within normal L&F)
What do you gain from doing so? (Improvinging usability?)
What do you lose from doing so? (Intuitiveness & familiarity?)
Don't simply do it 'To be different'
It depends on how wide you would define system look'n feel... But in general, you should keep it.
Do not surprise the user with differentiating from what he is used to. That's one of the reasons why we call him user ;-)
Firefox and Adobe products usually don't because they are targeting several plattforms which all have their own L&F. But Visual Studio keeps the typical Windows L&F. And, as long as you are developing only for Windows, so should you.
Apart from the fact that there is no well-defined look-n-feel on Windows, you should always try to follow the host platform native L&F. Note however that look-n-feel is just as much about how a program behaves as how it looks. Programs which behave in a counter-intuitive way is just as annoying as programs sporting their own ugly widgets.
Fraps is a good example (IMHO) of a program which is actually very useful, but breaks several user interface guidelines and looks really ugly.
If you're developing for Apple's Mac OS X or Microsoft Windows, the vendors supply interface guidelines which should be followed for any application to be "native".
See Are there any standards to follow in determining where to place menu items? for more information.
If you are on (or develop for) a Mac, then definitely YES!
And this should be true for Windows also.
In general, yes. But there's the occassional program that does well despite being not formatted for all the OSes it runs on. For example, emacs runs pretty much contrary to every interface guideline on OS X or Windows (and probably even gnome/KDE) and it's not going away any time soon.
I strongly recommend making your application look native.
A common mistake that developers who are porting an application to a new platform seem to make is that the new application should look-and-feel like it does on the old platform.
No, the new application should look-and-feel like all the other application that the user is used to on the new platform.
Otherwise, you get abominations like iTunes on Windows. The same UI design may be exactly right on one platform and very wrong on the next.
You will find that your users may not be able to pin-point why they dislike your application, but they just feel it hard to use.
Yes, there are valid exceptions, but they are rare (and sure enough, they tend to be the major applications like Office and Firefox, rather than the little ones). If you are unsure enough to have to ask on StackOverflow, your application isn't one of them.
Back in the old days, Help was not trivial but possible: generate some funky .rtf file with special tags, run it through a compiler, and you got a WinHelp file (.hlp) that actually works really well.
Then, Microsoft decided that WinHelp was not hip and cool anymore and switched to CHM, up to the point they actually axed WinHelp from Vista.
Now, CHM maybe nice, but everyone that tried to open a .chm file on the Network will know the nice "Navigation to the webpage was canceled" screen that is caused by security restrictions.
While there are ways to make CHM work off the network, this is hardly a good choice, because when a user presses the Help Button he wants help and not have to make some funky settings.
Bottom Line: I find CHM absolutely unusable. But with WinHelp not being an option anymore either, I wonder what the alternatives are, especially when it comes to integrate with my Application (i.e. for WinHelp and CHM there are functions that allow you to directly jump to a topic)?
PDF has the disadvantage of requiring the Adobe Reader (or one of the more lightweight ones that not many people use). I could live with that seeing as this is kind of standard nowadays, but can you tell it reliably to jump to a given page/anchor?
HTML files seem to be the best choice, you then just have to deal with different browsers (CSS and stuff).
Edit: I am looking to create my own Help Files. As I am a fan of the "No Setup, Just Extract and Run" Philosophy, i had that problem many times in the past because many of my users will run it off the network, which causes exactly this problem.
So i am looking for a more robust and future-proof way to provide help to my users without having to code a different help system for each application i make.
CHM is a really nice format, but that Security Stuff makes it unusable, as a Help system is supposed to provide help to the user, not to generate even more problems.
HTML would be the next best choice, ONLY IF you would serve them from a public web server. If you tried to bundle it with your app, all the files (and images (and stylesheets (and ...) ) ) would make CHM look like a gift from gods.
That said, when actually bundled in the installation package, (instead of being served over the network), I found the CHM files to work nicely.
OTOH, another pitfall about CHM files: Even if you try to open a CHM file on a local disk, you may bump into the security block if you initially downloaded it from somewhere, because the file could be marked as "came from external source" when it was obtained.
I don't like the html option, and actually moved from plain HTML to CHM by compressing and indexing them. Even use them on a handful of non-Windows customers even.
It simply solved the constant little breakage of people putting it on the network (nesting depth limited, strange locking effects), antivirus that died in directories with 30000 html files, and 20 minutes decompression time while installing on an older system, browser safety zones and features, miscalculations of needed space in the installer etc.
And then I don't even include the people that start "correcting" them, 3rd party product with faulty "integration" attempts etc, complaints about slowliness (browser start-up)
We all had waited years for the problems to go away as OSes and hardware improved, but the problems kept recurring in a bedazzling number of varieties and enough was enough. We found chmlib, and decided we could forever use something based on this as escape with a simple external reader, if the OS provided ones stopped working and switched.
Meanwhile we also have an own compiler, so we are MS free future-proof. That doesn't mean we never will change (solutions with local web-servers seem favourite nowadays), but at least we have a choice.
Our software is both distributed locally to the clients and served from a network share. We opted for generating both a CHM file and a set of HTML files for serving from the network. Users starting the program locally use the CHM file, and users getting their program served from a network share has to use the HTML files.
We use Help and Manual and can thus easily produce both types of output from the same source project. The HTML files also contain searching capabilities and doesn't require a web server, so though it isn't an optimal solution, works fine.
So far all the single-file types for Windows seems broken in one way or another:
WinHelp - obsoleted
HtmlHelp (CHM) - obsoleted on Vista, doesn't work from network share, other than that works really nice
Microsoft Help 2 (HXS) - this seems to work right up until the point when it doesn't, corrupted indexes or similar, this is used by Visual Studio 2005 and above, as an example
If you don't want to use an installer and you don't want the user to perform any extra steps to allow CHM files over the network, why not fall back to WinHelp? Vista does not include WinHlp32.exe out of the box, but it is freely available as a download for both Vista and Server 2008.
It depends on how import the online documentation is to your product, a good documentation infrastructure can be complex to establish but once done it pays off. Here is how we do it -
Help source DITA compilant XML, stored in SCC (ClearCase).
Help editing XMetal
Help compilation, customized Open DITA Toolkit, with custom Perl/Java preprocessing
Help source cross references applications resources at compile time, .RC files etc
Help deliverables from single source, PDF, CHM, Eclipse Help, HTML.
Single source repository produces help for multiple products 10+ with thousands of shared topics.
From what you describe I would look at Eclipse Help, its not simple to integrate into .NET or MFC applications, you basically have to do the help mapping to resolve the request to a URL then fire the URL to Eclipse Help wrapper or a browser.
Is the question how to generate your own help files, or what is the best help file format?
Personally, I find CHM to be excellent. One of the first things I do when setting up a machine is to download the PHP Manual in CHM format (http://www.php.net/download-docs.php) and add a hotkey to it in Crimson Editor. So when I press F1 it loads the CHM and performs a search for the word my cursor is on (great for quick function reference).
If you are doing "just extract and run", you are going to run in security issues. This is especially true if you are users are running Vista (or later). is there a reason why you wanted to avoid packaging your applications inside an installer? Using an installer would alleviate the "external source" problem. You would be able to use .chm files without any problems.
We use InstallAware to create our install packages. It's not cheap, but is very good. If cost is your concern, WIX is open source and pretty robust. WIX does have a learning curve, but it's easy to work with.
PDF has the disadvantage of requiring the Adobe Reader
I use Foxit Reader on Windows at home and at work. A lot smaller and very quick to open. Very handy when you are wondering what exactly a80000326.pdf is and why it is clogging up your documents folder.
I think the solution we're going to end up going with for our application is hosting the help files ourselves. This gives us immediate access to the files and the ability to keep them up to date.
What I plan is to have the content loaded into a huge series of XML files, each one containing help for a specific item. This XML would contain links to other XML files. We would use XSLT to display the contents as necessary.
Depending on the licensing, we may build a client-specific XSLT file in order to tailor the look and feel to what they need. We may need to be able to only show help for particular versions of our product as well and that can be done by filtering out stuff in the XSLT.
I use a commercial package called AuthorIT that can generate a number of different formats, such as chm, html, pdf, word, windows help, xml, xhtml, and some others I have never heard of (does dita ring a bell?).
It is a content management system oriented towards the needs of technical documentation writers.
The advantage is that you can use and re-use the same content to build a set of guides, and then generate them in different formats.
So the bottom line relative to the question of choosing chm or html or whatever is that if you are using this you are not locked into a given format, but you can provide several among which the user can choose, and you can even add more formats as you go along, at no extra cost.
If you just have one guide to create it won't be worth your while, but if you have a documentation set to manage then it is the best to my knowledge. Their support is very helpful also.