Best Gel Documentation System
Flaviano Bada
Documenting your product and its features can be highly time-consuming and requires a lot of attention to detail. Tools that support the features such as Markdown & WYSISWYG Editor, Category Manager, Article Redirect, Backup & Restore can help get the job done easily.
"@context": " ", "@type": "FAQPage", "mainEntity": [ "@type": "Question", "name": "What Is a Software Documentation tool?", "acceptedAnswer": "@type": "Answer", "text": "Software documentation tools make authoring and delivering documentation faster and easier, reducing the time it takes to create and manage documents. Many documentation systems allow you to publish your documents once they're finished and distribute them to internal or external users." , "@type": "Question", "name": "How to choose a software documentation tool?", "acceptedAnswer": "@type": "Answer", "text": "Documenting your product and its features can be highly time-consuming and requires a lot of attention to detail. Tools that support the features such as Markdown & WYSISWYG Editor, Category Manager, Article Redirect, Backup & Restore can help get the job done easily." ]
At my company we create Windows based desktop applications. In the past, we have created .chm files for our help documentation and have been happy with it. We have now been faced with some issues regarding the software we use to create the .chm and would essentially have to invest a lot of money to continue using this .chm creation software, which leads me to this question: Are .chm files the really the best avenue for providing help documentation?
I have done some research on creating PDFs with all of the elements that are in the .chm files such as a table of contents and links that jump to other sections in the document. Online help is not an option. Whatever solution we pick has to work without an internet connection.
Update: It looks like we have to use .chm for a few reasons, mainly because of its ease of updating and distributing (only 1 file). My runner up to this would have been html help, which is essentially what a .chm is anyway.
So, assuming you do need help, I'd suggest the best would be context sensitive help that can link to your web site with the latest up-to-date help information. You'd publish help as HTML, saving you from proprietary CHM production workflows.
As others said, you should look into generating HTML files that you ship with your product for help. One of our products (used in an environment without internet access) has been doing this for years and many users prefer it to the PDFs we also ship because the navigation is easier, the content lays itself out to fit the browser window, and the chunk size is smaller. Our HTML configuration also supports context-sensitive help, though we haven't implemented that yet.
A PDF is a nice presentation of page-based documentation, but if the user wants to avoid horizontal scrolling in order to read it he has to allocate a fair bit of screen real-estate. Depending on his monitor size(s) and the space needed by your application, it may not be possible for him to view the help alongside the application, which is a hinderance if he's using the doc to walk through a step-by-step procedure.
However, technical documentation is not the most effective manner to communicate to end-users. Increasingly, interactive protoypes are used to communicate with users. For an example, take a look at the Google+ demo. Elaborating this kind prototypes can be expensive. However, if a UXD process is used, those prototypes can be used at many stages of the process. So they may be worth the effort.
I'd go for tech writers editing HTML directly. Sharepoint Designer is free and "works just like Word" (actual quote), you'd need some setup and rules regarding styles, cross-linking etc., but it worked out.
Whether you bundle the HTML in a CHM doesn't really matter much. The main advantage of CHM over plain HTML is the Index and Full Text Search. There are some client site HTML search engines but I haven found one that's easy to use
There's not much point in documenting dialogs and long lists of menu items anymore. Provide a task-oriented manual, lots of How-To's and sample scenarios. Answer questions. Don't describe dialog elements (they should be self-descriptive), but how they interact with others and affect the result.
Regardless of what you think of them, Adobe generally have pretty good help mechanisms within their application. From what I can see, they're bespoke alternatives to CHM, but seem to be HTML based. I haven't the latest versions of their stuff, so I'm not sure how they do it now.
Often, there's a requirement for there to be a user guide, which then drives the main documentation effort. Then online Help can wind up as a re-purposed or derived form of a book-like guide -- even if the guide is never printed but only exists as PDF.
These efforts can be OK or lousy. Simply slapping a PDF up on screen is not great. You have to put some work into (re-)organization, bookmarking, hyperlinking, searchability of the user's guide to make it useful in the program.
You have to choose your delivery format based on audience, attention span, need for printed materials. Internal business applications call for training classes, which can also drive demand for a book or other training deliverable.
If your application can get by without explaining anything or showing any additional help for users while they're using it, hooray, the developers hit the jackpot and probably had a team of writers and tech communicators working alongside them.
That's almost never the case. Almost all software needs to display, in-app, some "how do I" and "how does this tool work" Help topics. These days, the easiest ways are CHM (compiled) Help and HTML-based help, with interactivity delivered through Javascript. You can have an HTML Help system that's identical to CHM by using one of the expensive Help development environments or using free editors. I had a lot of success with a library, FAR Help compiler, a kind of combined CHM / Javascript workshop that is nearly free.
I'm become convinced that HTML5 is the way to go for any online documentation/Help system. With Javascript, CSS, SVG graphics, many libraries, you can deliver all the interactivity of any website and include animations, videos, full-text search, AI, 3D, and more.
There is no perfect development environment for all that, because it requires writing and language tools that code editors alone don't have. There are big publishing packages that promise multiple output formats, but its impossible to be perfect at too PDF, CHM, HTML authoring and output.
Visual Studio along with a content-management database and word processor (probably Word) would be one set of tools for dynamic HTML 5 Help systems. So Would Flare or FrameMaker. You still likely need a web editor (MS Expressions Web, Dreamweaver, etc.) for times when you have to work directly in the HTML. You need Photoshop or other image editor, and a versatile capture tool.
Most importantly, if you want excellent online help, you need experienced technical writers, who are really interactive documentation developers and communication specialists and much as they are "writers."
I'm looking to implement a pretty hefty documentation project for my marketing operations apparatus. I want to cover the automation process, how workflows work, what custom fields trigger in HubSpot/SFDC, FAQs, what to do if, and even documenting issues we uncover and how they were solved, etc.
Hi @jmillerokc ! Thanks for tagging me @TiphaineCuisset , documentation is one of my favorite topics, I'm actually teaching a class on it right now!
My #1 tip is to use a system your team is already using daily so you don't have to teach them a new tool IN ADDITION to teaching them new habits about creating, using, and updating documentation.
If you're more concerned about documenting for yourself right now, getting the first draft of all the docunentation done, my advice is use the tool that's easiest for you. You can always delegate/hire someone later to move it into a different system but it would be harder to delegate or hire anyone to do the first draft of it -- for someone else to get that information out of your head!
So as you mentioned, the HubSpot knowledge base would be a good place to store documentation, if your team is using HubSpot daily already, you have reasons to purchase Service Hub it in addition to the knowledge base (HubSpot has a lot of material to help you make a case for that, if needed!). You can use it as the main library and link articles to, or embed, flow charts and other items if an article format isn't as useful.
If you currently use a project management system, ideally one shared across the team or company, that can be a great place to store documentation since ideally everyone is already in that tool daily.
If you use Google docs as a team and people are used to navigating to find information in there, and can find what they need, that can be a good option at least to start with, to build out the documents and get people in the habit of using and updating.
There are tools like Notion or Guru that integrate with Slack, if your team is a big user of Slack as your "home base" for work during your day...I just caution people to not get too wrapped up in spending weeks on researching documentation tools when its a better use of time to spend those weeks completing your version 1.0 of documentation in whatever tool is easiest for you and your team. Using what you have now. Since tool research can be much more fun (and distracting) than doing the documentation
Resources:
Recent HubSpot admin HUG with my previous boss Nicole about our documentation learnings
Talk I did at world certification week
I may have taken over this podcast topic to talk about documentation haha
4 part blog series on HubSpot community blog, starts here
Class