Why your documentation stinks (and how you can make it better)

Okay, so maybe you’re the exception and your software documentation is perfect. But if you’re like most companies – and we were right there with you – your documentation is confusing and out of date.

Our solution? In case you haven’t seen it yet, we put the Windward docs on a wiki — and so far it’s working out really well.

Introducing the new Windward documentation wiki. We switched formats this summer and it has made our lives easier.

The new documentation wiki solved a bunch of problems:

    • Old information. Because we release features when they’re ready – we don’t save up a bunch to release every nine months or whatever – our documentation was a moving target. It was out of date days after it was printed. But now when a developer checks in the final code for a new feature, he or she is required to document it in the wiki. This means the documentation is (usually!) up-to-date.
    • Missing details. The level of detail and description of why you would use a new feature, as well as how, has jumped substantially. When a developer has checked in code, the “proud parent” wants to describe the new tool in detail, immediately.
    • Lack of feedback. Before, if a customer found a mistake or unclear detail (yes, we’re human), editing the documentation was an arduous task. Now customers can edit or comment on the wiki at any time. We get immediate feedback about what works (and what doesn’t).

But we also found not all wikis are alike. We started off using a really popular one, but it had two fundamental problems.

One, the search feature didn’t work across all product sites. You could type “java reporting” and never find what you were looking for because you were in our java reporting engine section and not in our java reporting design tool section.

Two, it lacked an automated table of contents. No breadcrumbs, so you didn’t know where you were in the site or what related info might help you.

We just switched to one that’s WAY better. It has superb organization. It integrates with our online helpdesk. And its global search engine helps you get the information you need – fast. Check it out at http://wiki.windward.net/ and let us know what you think.

 

A Sneak Peek at Upcoming Reporting and BI Changes

We’ve been pretty busy behind the scenes here at Windward with our upcoming reporting and BI changes. Here’s what you can expect from us in the coming months.

  • AutoTag Version 11. We roll out a new version of AutoTag roughly once a year, and it’s that time of year again. (Remember – upgrading is free as part of your yearly maintenance contract, so we invite you to check these out for yourself.) We’ve added some features, improved some others, and sent a few more to that great recycle bin in the sky:
    • More native data sources. Along with all the data sources you’re used to (SQL databases, XML files and Excel spreadsheets), you can add support for cubes and the Microsoft BISM data source to the list of places AutoTag can “talk” to. This means your programming team doesn’t have to spend time getting your data into a format one of the aforementioned data sources could read – and can instead hang out and play a mean game of Cubicle War.
    • More flexibility in charts and dashboards. When you use tags to create a chart in Word, you can make the chart be a chart in the output – where you can change the colors, title, or otherwise reformat it as you wish. (If you don’t want end users to have this option, you can also make the chart static.) This feature was pretty popular, so now you can do the same when designing reports in Excel and PowerPoint. And this leads to:
    • Still more flexibility in charts. If you have a chart in a template that is a regular Office chart (ie. not generated through a chart tag), this example shows how that will carry over to the report.
    • More tags. The bookmark tag will let you place bookmarks in the template – through a call to your data source – that can be linked to from hyperlinks.
    • Giveth some, and taketh away some. We’re cleaning up the program a bit by deprecating features and replacing them with, well, better ones. So bye bye function tag (hello custom functions) and beans (to be replaced with IEventHandler.) And yes, you will see more on these new items in a future post.

Along with AutoTag upgrades, we’re working on some other improvements.

  • AutoQuery on Javelin. Right now our business intelligence tool is available as an Office add-in, but it doesn’t yet have some of the cool features that Javelin offers, like an automatic scheduler, or Web browser access. That’s about to change. Soon you’ll be able to use your browser to look at a report and run ad hoc and drill down queries.
  • Wishbone. We mentioned this in an earlier post, but just in case you missed it… Wishbone is a way to find connections between words and Twitter phrases. Input a word, and Wishbone shows you what’s trending around that topic. Depending upon how you look at it, Wishbone is either a useful tool for analyzing social media data or the best way since Facebook to waste time.

###

 

Top 10 Report Design Tips

Get Your Report to Look The Way You Want

You’ve probably already figured out you can produce reports and documents in a lot of different formats (PDF, HTML, DOCX, etc.) – way more than most of our competitors. And that leads to a big challenge in report design:

With so many different output options, how can you make sure the template renders the way you expect?

On the back end, we’ve done a lot of work trying to make the output report identical to the template, pixel for pixel. But it won’t be perfect, for a bunch of reasons. (Some have to do with how the report design tool, Microsoft Office, formats itself differently according to a system’s graphics and printer drivers. Others have to do with vagaries of specific output formats like PDF.) And we can’t do a lot about that.

BUT what we can do is help you make it as close as possible. Here’s how.

1. Use hard page breaks. If you want a page to break at a certain spot, use Word’s hard page break command. The same principle works for other types of breaks, like line breaks and column breaks.

2. Fall in love with TrueType and OpenType fonts. Yeah, there are other types of fantastic fonts out there. But they are closely tied to their code page and can lead to some unwanted – and frustrating – formatting hiccups.

3. Skip absolutely positioned objects. Instead, try to position relative to a paragraph, column or other item. (Here’s a good tutorial that explains Absolutely Positioning a Picture where you can learn more about and glean how to use relative positioning instead of absolute in your document. And the necessary disclaimer — we don’t know or endorse the author.)

4. Sparingly use “keep lines together” settings for paragraphs. A paragraph that was 3 lines in a template can be 100 times (or more) that many in a report. They may not all fit together in the final output.

5. Ditto for “row header” settings for tables. Ditto again on the reasoning.

6. Use set values in table column widths. Set table column widths using inches, centimeters, points or percentages – not AutoFit. AutoFit will not necessarily match because of how MS Office works (and that’s as detailed as we’re gonna get!) Check out this Microsoft primer on using AutoFit.

One template, so many output format possibilities!

7. Give yourself some wiggle room. Don’t try to cram stuff into every last corner of a page. Sooner or later the metrics will space out the glyphs more (yeah, that’s the explanation we got from our development group – we have no idea what that means, either) and one page will spill over onto two.

8. Minimize using nested tables. We’re not recommending you get rid of them altogether – they can be great reporting tools – but if you have another option, take it. For example, if you want to put a border around a page that contains a table, instead of creating a table for the entire page, use the page border.

9. Make table borders as simple as possible for PDF outputs. Windward uses what are called polylines. In a PDF doc, it draws one polyline for the outer border, one for each internal row border, and one for each internal column border. If you can, keep each one to a single width, color and style.

10. Design Word templates in DOCX or WordML, not RTF. RTF is notoriously funky (the technical term for “poorly formatted”) and Word doesn’t always follow it. Odds are RTF templates will have more problems than DOCX or WordML.

Hope this helps!