Archive for the 'Documentation' Category

This year our Dr.Explain help tool team is proud to be a sponsor of The Conference for Software User Assistance by WritersUA.

The focus of the Conference for Software User Assistance is on developing the best possible user experience for all types of software applications through well-designed interfaces and helpful and accessible support information. The Conference includes over sixty sessions Sunday, March 21, through Wednesday, March 24.

The Conference for Software User Assistance

Success in improving the software user experience depends on applying the right skills and technologies to maximum advantage. The conference targets this need by providing an array of sessions demonstrating effective techniques, case studies demonstrating best-in-class designs, technology updates, and much more.

This year’s Conference features seven interest areas with information on:

  • Emerging Skills
  • Technology Updates
  • Design Strategies
  • Tool Techniques
  • Content Development
  • Open Standards
  • Special Interest

Registration is open! Early discounts in Effect!

Dennis Crane

Is your on-line help manual SEO friendly?

Recently, we’ve discovered that up to 40% of the Dr.Explain website’s organic (non-paid) traffic that comes from search engines do actually land on pages of our on-line manual. This proves that on-line documentation is not only a helpful tool for existing customers and users. It’s a good marketing and sales tool as well.

If you already have published your product documentation on your website then check if it’s properly optimized from search engines’ points of view. Don’t try to over-optimize your on-line manual. Just follow the simple rules to make your help pages to display higher on a search engine results page (SERP) for relevant search strings:

Use appropriate words and terminology in content.
This must be the same terminology that your target audience uses daily. They will likely use the same words and terms in search requests.

Use unique and keyword-based titles for your pages.
“Topic 2330: Transparency” is a too general title. “Transparency Settings - Cover Designer Advanced Customization” is a better title.

Use topical keywords in file names of your help pages.
Again, “topic2330.htm” is a bad name. “cover-designer-advanced-settings-transparency.htm” is a much better name.

Use header tags for titles.
Wrap your headings and subheadings in H1, H2, H3, and so on tags to make them more meaningful for search engine ranging algorithms.

Mark specific terms and phrases with bold.
Write specific terms and targeted keywords in bold (strong) font to highlight their importance and relevance.

Cross-link your help pages.
Insert links to certain help pages in content of other pages. Use keywords for link text. For instance, “To read more about boxshot rendering click here is a wrong way. “Read more about boxshot rendering is a SEO-friendlier approach.

Create or solicit external links to your help pages.
A big number of external links that point to your help pages means a bigger page rank and higher position on SERP. Put links to your on-line manual wherever it’s possible on your product and company websites, partner websites, support forum, and so on. If some topics of your documentation can be considered as a standalone articles with useful content (trouble shooting, glossary, reviews, problem overview, etc.) then try to gently solicit links from third-party websites: topical forums, article directories, industry blogs, and resource collections.

User manual is a huge bunch of words, highly targeted words, which are specific to your product’s market. People use these words in their queries when they are looking for specific solutions on Google, Yahoo, Bing, or other search engines. On-line manual will increase your web site rank in relevant search results and will bring highly targeted traffic to your web site. Let the manual work not only for your users, but for your business as well.


You still have not made an on-line manual for your product?
Make it with
Dr.Explain - help authoring and documentation writing tool.
Improve your customers’ user experience and create additional sales channel.

Being a software vendor is a fantastic job. Meeting interesting people with out-of-the-box vision is one of the most attractive sides of my job.

Balam J. Abello Today, I’m happy to introduce you an interview with Balam J. Abello. Balam is a talented engineer, futurist, writer, and IT consultant with many years of extensive experience in such revolutionary corporations like IBM and American Express. Currently, Balam is researching a concept of Collective Intelligence in a modern society. I convince you to visit his site www.balam.org to read more about Balam’s works and ideas. Let’s speak about how the concept of Collective Intelligence may affect the information technologies.

Balam, could you please explain a key idea of Collective Intelligence concept in several words?
At the crux of CI is the idea that under certain circumstances a “diverse” and preferably large of group people are often more accurate than a single individual; even if this individual is an expert. This is particularly true in the case of complex systems.

In a nutshell, Collective Intelligence uses the aggregate opinions from groups of diverse and independent people to apply it to several types of problems, one of which is the decision making process.

Did this concept exist earlier or it’s a product of the modern technological society?
This concept has existed before. In fact, one could even say that it has been around since the beginning of cellular organisms which is about 3.5 billion years. As a scientific discipline CI became of age in the 20th century. But in the past couple of decades, CI has come into view. This means that a lot of the theoretical postulates have come true on the Internet.

What convinces people to participate in collaborative projects which are mostly non commercial? This is hardly an opportunity to get paid.
Perhaps idea that all human activities should seek financial rewards as its main raison d’être is a distortion from past human history. This perception has reached unprecedented proportions during the past 300 years and especially during that last 50 years with the advent in some cases, of unbridle depredatory capitalism.

Collaboration is at the heart of human behavior. Mathematics, language, music, farming and culture, to name a few, are huge collaborative efforts. Let’s not forget that the Internet is proof positive of daunting and massive collaborative efforts.

This question has been asked a lot in regards not just to CI but more importantly about the Open Source movement. People derive all kinds of altruistic and non-altruistic benefits from collaboration which are not necessarily monetarily driven. Although, this does not preclude that for many people their motives are driven by a monetary reward and this is fine too.
Lastly, I content that as people become more educated, e.g. acquire more knowledge, there will be a tendency to work for the common good which is counter to traditional predatory practices, which in many case have been responsible for the “tragedy of the commons.”
But let me make it clear that I don’t argue against making a profit. After all my IT consultancy practice has a lot to do with this. Additionally, major corporations throughout the world are looking into CI as a means to further their enterprises in an ever more complex world.

You believe in the society that relies on Collective Intelligent, not on leaders, elite or governors. What about moderators, administrators and super users who significantly affect the work of almost any existent collaborative project? Isn’t it the same untrue Democracy?
Let me say that I look forward to a society that relies more onto itself with a lot less blind obedience to a leadership hierarchy. But my position is not black and white which means that I don’t see an absolute necessity of leaderless groups. What I think could or might happen is that these power hierarchies are going to be flatten significantly, thus reducing, but not eliminating the need for “command-and-control.”

It is quite clear that there will continue to exist an ever increasing need for moderators which I prefer to call “mentors” as well as administrators and a great number of other functions too. My thesis is that these “leaders” people should not have extreme power to decide the group’s agenda. These people should act more as consultants to their organizations thus creating a little more separation between self-interests and desired outcomes. If we talk about teamwork we should try, in as much as possible to create an atmosphere where members all are encouraged to have a voice and prevent the group from falling prey to “groupthink.”

However, when it comes to democracy, it is quite apparent that throughout history the will of the people, which is usually less drastic or extreme than that of individuals, is hardly ever really taken into account. Many campaigning politicians pay only “lip-service” to the people during election cycles. As soon as the “leaders” are elected they go ahead and do precisely what they want and this is sometimes the opposite of what the people, who voted for them, wanted in the first place. And, this seems to be a universal phenomenon. So I don’t criticize any given country or institutions for this behavior. Instead I look at it from the “systemic” point of view and realize that if any changes are to take place then these should occur at the “systems” level. In this case, practical approaches toward CI implementations might really help.

Do you believe in Web 3.0? What could it be?

Yes I believe that WEB 3.0 will be a major contributor to change. In fact we are in the middle of implementing WEB 3.0 environments but this will:

  • Take anywhere from 5 to 10 years to implement
  • Will not be readily visible to the standard user
  • Will generated huge benefits bringing a higher order of Artificial Intelligence to the masses.

You could think of WEB 3.0 as the plumbing necessary for the water (intelligent information and knowledge) to flow. In other words, getting most of the billions of web sites to start adding the necessary tags (taxonomies) necessary for computer-programs-and-sites to automatically talk to each other creating the possibility for personalized intelligent avatars or agents, will take some time.

What kind of software applications or IT systems are worth developing while awaiting for Collective Intelligence to get hold?
Now, this is a very difficult question to answer. But my suspicion is that there is a huge universe of possibilities. What is interesting is that as I answer these questions there are probably thousands upon thousands of people experimenting new ideas for such applications. This creative-ecosystem is thriving.

Nevertheless, one trend is for IT applications to be more and more custom oriented versus massively standardized applications. Niche markets seem to be one strong trend.

What will be the main trends in technological and informational progress for humanity?
Once again this is a very difficult question to answer. Personally, I feel that all possibilities are open for expression. I try to think not so much linearly e.g. cause-and-effect when it comes to future trends. This makes any kind of prediction so much more difficult and consequently prone to error.

I will say that I believe that from the information / knowledge point of view, we are creating a “global-super-brain” which is already having profound effects upon all peoples in the planet. Furthermore, I also believe that the future will be extremely transparent. Secrets will tend to disappear on the web. And we see this already happening.

For example, when it comes to political candidacies, with just a few mouse clicks we can find out just about anything about prospective candidates; including such things as their voting records and all kinds of personal information which would allow us, to make informed decisions.

A special final question for our audience: What advantages and techniques of Collective Intelligence concept can be adopted and applied by a one-man shop software vendor (microISV) or by a small software development team?

The increased power of technological tools allows small groups of individuals or even single individuals to achieve great projects. A case in point is the history of Linux. Let’s remember that a single individual created the kernel for Linux and the first thing that he did was to released to the general public for it to do as it pleased and as a byproduct for people to help him fix Linux’s bugs. This was the case of a single individual taking advantage of the “Collective Intelligence” of large numbers of people. The end result has been a whole new multibillion dollar industry.

Therefore, a microISV could organize his or her software project to leverage the power of the people, which in computer science could equate to massive parallelism. Additionally, the techniques of WEB 2.0 collaboration are very well defined and have proven to work successfully. These techniques are also available to the microISV, today.

Thank you, Balam!

I invite everyone to visit Balam’s site www.balam.org to learn how to collaborate for a better World.

Dennis Crane

Going to Write Another E-book?

A professional friend of mine, technical writer Keith Johnson, offered me an opportunity to write a guest post for his excellent Great Documents - technical writing blog. During several chat sessions with Keith we were discussing various questions of collaboration, social networking, information exchange and sharing. This discussion convinced me to summarize my thoughts about e-book writing in a single post. Recently, Keith has kindly published my post in his blog.

Check it out:

Going to Write Another E-book?

… almost everyone finally arrives to the idea of summarizing the whole knowledge on a certain topic in a single document or informational product …

Thanks for the opportunity to share my ideas in your great blog, Keith!

Scott, an ISV-entrepreneur, on BoS forum has recently complained that since their company had reached a new level of technical documentation the number of service requests grew up.

That’s an interesting effect!

Scott wrote:

Two reasons for this, based on feedback from customers seeking support:

1. Documentation is now so comprehensive that it is intimidating. People see a 1000 page manual and say “no thanks - I’ll just call customer support instead.”

2. Documentation has so much cool stuff described, that it makes people’s imagination stimulated and they start thinking of other, even more exotic stuff they want to do but can not figure out and start a service request for it.

Thus, the common solution to service requests - better documentation - actually causes more service requests, not fewer.

Is this really true and good documentation will harm to your business?

I think that only a big number of pages doesn’t mean that the manual is good. In documentation, users look for problem solutions. The more important thing than the number of pages is the structure of the manual and simplicity of search mechanisms (indexes, built-in troubleshooters, context help, etc. ).

Recently, we needed a presentational video for an affiliated service that allows health conscious people to track their diabetes, blood pressure, or body weight records and to share the results.

The main difficulty of the project was a voice-over for the video. We needed a clear, calm and native English speech but there are no native English speaking members in our team.

The two services helped us in this matter.

EditAvenue.com is a proofreading and editing service marketplace that helped us to proofread the draft of the written script for the voice-over.

If you are non-native English speaker then through EditAvenue you can access hundreds of professional editors who can correct and refine your written communication. The prices start from about $4 per page (300 words). A relatively small task may be accomplished likely in the same or next day even if you don’t pay for express delivery service.

Once we’ve received the edited script we started to look for a talent to record a voice-over for our demo. That was a problem until I spotted a link and recommendation for Voices.com on JoS boards. That’s was amazingly helpful service!

Voices.com is another marketplace where you can hire a voice artist for almost any type of job - from commercials and presentations, to cartoons and audio books. For presentations, the rates are about $300 per 5 minutes of speech.

After we had posted a job description we received about a hundred of responses with sample records in several hours. We selected a talent, made the deposit and received the final audio files by the end of the day. That was really, really cool.

I highly recommend the above services to everyone who needs to create impressive presentations for his\her products.

Here you can see the final video with the voice-over.

Any macro- or microISV collects a pile of miscellaneous information while developing, promoting and supporting its software products. This includes:

  • know-hows
  • algorithms
  • company policies
  • programming, development or marketing techniques and tricks
  • standard solutions and workarounds for certain issues
  • collection of links to various resources
  • how-tos
  • use cases
  • experience with third-party software, tools or services
  • research and analytical reports
  • white-papers and articles
  • statistics
  • industry news
  • events
  • to-do lists
  • contacts
  • … etc …

The list is theoretically infinite. In practice these odd bits of information are usually stored in different unrelated sources: e-mails, help files, document files, source code comments, browser favorites, or simply as sticky notes on your desktop.

This causes the following problems:

  • Complicated access to important data. You can simply forget where they are stored.
  • Risk to occasionally lose some significant files, e-mails or paper notes.
  • Difficulties in collaborative use of the information. Nobody in your team knows where you store your sacred knowledge. In the same time, you have no idea where your colleagues keep their information.
  • Ineffective re-use of information. You often have to re-invent something that you’ve already done or research something you know.

To overcome the problems you must accumulate all bits of your corporate information in a single knowledge base with collaborative access.

Large companies may setup custom knowledge base as a part of their corporate portal, e.g. with MS SharePoint server. But I speak for small ISV companies today …

Relatively small companies like ours may use Wiki engine. I’d personally recommend MediaWiki. It’s free and easy to install on any Apache/PHP/MySQL hosting though it’s very powerful and flexible. The famous Wikipedia uses MediaWiki engine.

Although there are many useful extensions and modifications for MediaWiki you may start with just a few of the most important ones:

  • SimpleSecurity allows setting access privileges for users. So, you can limit access to certain pages for some members of your team.
  • SyntaxHighlight_GeSHi allows to insert source code sections into articles and to highlight the syntax. It’s very useful for software development companies. This extension requires additional installation of GeSHi library that supports dozens of programming language syntaxes.
  • CharInsert adds toolbar to the editor for quick insertion of Wiki codes.

Setup wiki today and start collecting your information there. Each time you or your colleagues have discovered something important for your business add it into your knowledge base. It requires just several minutes to add a new Wiki article. After several months you will be surprised at how valuable knowledge base you have. This will increase your team productivity and will become a kind of the company assets.

Just don’t forget to protect your knowledge with password. Your competitors want your knowledge too. :)

If you are serious about writing a good documentation for your software either with our help authoring tool - Dr.Explain, or with another one, then you definitely should subscribe to the following blogs on technical writing, software help and documentation authoring. To be honest I even included links to blogs of our direct competitors.

I say “Thank you!” to our fellow customer and partner Craig Prichard, a technical communicator, who gave me many new links for this list.

Cherryleaf Technical Authors’ Blog
A blog site from Cherryleaf, a technical communication UK company by Ellis Pratt. Ellis regularly gives comprehensive review of the industry news as well as practical articles on technical writing.

Harry Miller’s Technical Writing Blog
Harry’s blog contains not only written content about documentation, technical writing, and technical editing, but many podcasts as well.

HelpStuff Blog
A famous blog by Char James-Tanny (JTF Associates) about all aspects of helping software end-users.

I Came, I Saw, I Learned…
A blog by Kevin A. Siegel who has written more than 100 step-by-step computer training books and has been a software trainer for more than 15 years.

E-Learning, Moodle, Technical Writing, and Training
William Rice is an educator, trainer, and writer. Most of his posts are either articles or tutorials about his professional pursuits: e-learning, Moodle, technical writing, and training.

I’d Rather Be Writing
A blog about technical communication by Tom Johnson. Tom covers many topics from any kind of user guides and design documentation, to audiovisual tutorials and drawings, or other explanatory content that is of a technical nature.

Gryphon Mountain Journals
Ben Minson is a technical communicator. He creates documentation and training on applications that are produced in-house. Writing is what Ben does. He thinks that when he die, the mortician will have to pry the keyboard loose from his cold, dead clutches.

OneManWrites
That OneMan is Gordon McLean, a technical author with a passion for good communicative information products. Another Gordon’s passion is web design. In his posts Gordon keeps balance between practical issues and theory of technical writing.

Charles Jeter Blog
Charles writes mainly about technical communication aspects in Web 2.0 world, e.g. work-flow collaboration and e-learning.

User Assistance
An exploration of issues pertaining to online help by Michael Hughes, PhD. As you can see from the blog’s title Michael focuses mainly on embedded user assistance, usability issues and user behaviour.

Just Write Click
A blog by Anne Gentle, a senior technical writer who is blogging about technical writing, information architecture, topic authoring, social media, and other communication technologies.

Mike’s Web Log
In this blog Mike Pope, a technical writer, covers various topics from writing and editing, to teaching and movies, and to politics and musics.

monkeyPi
An interesting point of view on usability, visual & technical communication, and software design.

Great Documents
In this blog Keith Johnson, a technical writing & software documentation specialist, gives many useful tips not only about documentation writing but on successful blogging, SEO, and social networking.

Scott on Writing
Scott Mitchell is a freelance writer, trainer, and consultant. In his technology-related blog Scott talks about technical writing, technology, and ASP.NET

Sharon’s MadCap Blog and Mike’s MadCap Blog
The two blogs by Sharon Burton and Mike Hamilton from MadCap Software. It’s always interesting to know what your competitors do :)

Technically Speaking
Paul Pehrson is another technical writer who blogs about various aspects of his job: writing tools, software, grammar, technologies and other important topics.

The Content Wrangler
A great resource for everyone who deals with technical content writing, editing, publishing and delivering. There is a lot of practical articles and industry news.

Communications from DMN
Aaron Davis and Scott Nesbitt, two experienced technical communicators, post their ideas and opinions, as well as links to information that they find interesting and hope that you will too. As you will see from their posts, Aaron and Scott have a wide range of interests when it comes to technical communications.

HelpScribe
A pretty young but very interesting blog by Craig Haiss, a technical writer. Craig started his blog to share his professional knowledge with colleagues. That’s great!

Usable Help
A blog of Gordon Meyer, an interaction and instructional designer. Gordon is a professional author and speaker on the topics of help system design. His posts on software help, usability and testing are always very practical and focused.

Of course there are many other blogs on help authoring, technical writing, e-learning and technical communication. I listed only the most popular and active, i.e. with new posts in 2008. If you know other good blogs on these topics, please add them through comments. Thank you!

The software improvement advice, techniques and ideas that I post here are taken from our real practice. I try to keep this blog practical and hype free. This post is a rare case (the previous one was about 9 months ago) when I’d like to tell a little about our own products.
During the recent months we have been working actively to make new versions of our existing products and to develop a new product as well. Recently we have released two new products.

Dr.Explain 3.0

Dr.Explain v.3.0 ( http://www.drexplain.com ) is an innovative software documentation tool. Thanks to unique technology, with Dr.Explain you can produce attractive and professional looking help files just in a few hours, not in days.

The Dr.Explain captures windows, dialogs, and forms from live application and web pages, makes screenshots, and automatically adds interactive references to all controls. You have not to spend hours annotating your software GUI. Focus on your content - Dr.Explain will do all the tedious work for you. The program can produce CHM, RTF and HTML help files with annotated screenshots, live menus, cross-references, and navigation from a single source file.


Dr.Explain concept

What’s new in v.3.0

  • The new capturing engine captures and automatically documents windows, menus, GUI elements, web pages, and even flash applications
  • Revamped text editor allows pictures, tables, lists, fonts, multibyte encoding, RTL mode, etc…
  • Enhanced topic management supports topic statuses, marking and locking\unlocking
  • Lots of other improvements including optimized export routines, Google sitemap generator, predefined macro variables, and many more improvements and tweaks.

The new version download: http://www.drexplain.com/download

TBS Cover Editor

TBS Cover Editor ( http://www.trueboxshot.com ) is a full featured software box cover creator with 3D rendering and template library. We accomplished the project in partnership with True BoxShot Software.

With the TBS Cover Editor you can create your 3D box shot design in a single flat worksheet. Say goodbye to separate designs for each side; no more design slices in many image files. The single-sheet concept of the TBS Cover Editor allows you editing of all box sides on a single screen. The real time 3D preview immediately shows how your 3D box shot output image looks like without switching between different windows or applications.


TBS Cover Editor Box shot template library TBS Cover Editor box shot

With the TBS Cover Editor no additional expensive third party tools are required. The program supports all the steps of box shot creation: from drafting and design, to 3D scene setting and image rendering. You can create professional-quality 3D box shots with no extra expense in a single program. The TBS Cover Editor comes with a brilliant collection of software cover design templates for various types of software. You can make a box cover in less than two minutes.

The TBS Cover Editor has a powerful rendering engine that produces realistic 3D box shots by applying original 3D rendering and ray casting algorithms. Your every box shot will look as if it is made by a studio.

More details: http://www.trueboxshot.com

Both these products will automate the most tedious and time consuming routines of your software business – software help and documentation writing, and graphical design. The Dr.Explain and TBS Cover Editor will help you present your software product in a professional manner with minimal efforts. As a software vendor you may focus on your business growth and leave the dull operations to the specialized systems.

During the last months I tried not to aggressively promote our flagship application Dr.Explain in this blog. I’d like the ISV Kaizen Blog to be not an advertorial but a collection of simple tips and tricks useful for most of ISV and mISV.

This post is an exception because today we have a good news. Indigo Byte Systems officially released Dr.Explain 2.6. There are about 25 new features and enhancements in the new version. So, I’d like to tell you a bit more about the Dr.Explain today.

What is Dr.Explain:
Dr.Explain v.2.6 is an innovative software documentation tool.
It sounds boring, doesn’t it? So …

What benefits will Dr.Explain bring to your ISV business process:
Thanks to unique technology, with Dr.Explain you can produce attractive and professional looking help files just in a few hours. That would otherwise take days to create them manually.

The Dr.Explain captures windows, dialogs, and forms from live application, makes screenshots, and automatically adds interactive references to all controls. You have not to spend hours annotating your screenshots. Focus on your content - Dr.Explain will do all the tedious work for you.

The program can produce CHM, RTF and HTML help files with annotated screenshots, live menus, cross-references, and navigation from a single source file.

You can read more about Dr.Explain and download a free trial on http://www.drexplain.com

What new benefits does the version 2.6 bring to users:
Let’s name just the most important:
* Better recognition of Delphi and other programming languages controls
* Many usability improvements
* More Hot Keys
* Better keywords management
* Optimized output routines
There are 25 new features in the update.

I think you may also be interested in the Dr.Explain featured reviews and user testimonials.

One more good news from Dr.Explain
Nowadays, Dr.Explain and True BoxShot run the mutual discount program. If you order either Dr.Explain or True BoxShot software you will receive $15 discount for the second product. Now you may add two useful products to your ISV toolbox and save money.
More info: http://www.drexplain.com/order

From Kaizen point of view, Dr.Explain will save many hours of your valuable time that you may better spend on product development and promotion rather than on boring documentation writing. The tool will easily pay for itself on the first project.

Next »