Arnt Gulbrandsen
About meAbout this blog
2012-04-23

FAQ handling

FAQs happen, and have to be handled. There are four ways. A sorted commented list (I promise this won't be a rant):

Do nothing. A valued approach, and there is much to say in its favour. For an opensource hacker who's basically writing code to scratch his own itch (using the male pronoun seems safe in this context) there's no intrinsic reason to care about FAQs at all.

Variants exist. I remember a case where patch to resolve a platform-specific compile error which caused FAQs was rejected because the relevant maintainer hated macs!!!.

Write a list of FAQs which people are supposed to read. This is neat for open source projects, it allows people to enter the project by doing something easy. But it's not actually good.

A good solution would make the problem disappear. This approach allows the problem to form during in the user's use of the program, allows the problem to be put in words, but prevents (mostly) the question from being put to the maintainers. I call that a firewall to shield maintainers from their software's problems.

And, also, dealing with the FAQ lists can be beastly for mortal users — the C++ FAQ/lite must weigh three kilos when printed out.

Answer the FAQ in the documentation for the relevant feature, if any. This is one tick better than the previous, if you ask me, since a user doesn't have to look up the problem in two locations. But it still allows the problem to be formed in the user's work, and navigating the documentation to find the answer may or may not be within reach of a mortal.

A digression perhaps, but when I asked Mikrotik Support what interface wireless set disable-running-check actually does, they not only answered me, but also fixed the documentation for that setting.

Edit the code to make the FAQ go away (or at least become an occasional rather than frequently asked question). This is good. This prevents people from having problems, which is two steps better than merely answering each problem after it's bothered the user.

In the Mikrotik case, this could've been done by making the builtin tab-tab help answer the question at that point in the interface. Usually it takes more work.

Choosing an opensource licence

Last night I read that use of the GPL is declining, ever faster. Makes sense. And makes me want to braindump another minor aspect of Trolltech's history, with a bit of a comment.

Trolltech started using 100% closed licensing, then, when I suggested it a few days after being hired, gradually released Qt under ever more permissive licenses. (more…)

2012-04-17

Web pages without URLs

You'll need content to test your new server.

To generate sample test content

  1. Build the AESPackaging sample (for more information, see Packaging Samples) by following these instructions:
    1. Install PlayReady Server SDK. For more information, see Installing PlayReady Server SDK.

Those links do not lead where you think they do. There are indeed web pages they could lead to, I have the pages. But I cannot see them in the address line of the browser, and even if I could, I couldn't give them to the colleague whom I'd like to read them and follow the instructions, because the files are on my machine.

Copying them to the web is difficult.

I despair.

Use the source wisely, Luke

No matter what the documentation says, the source code is the ultimate truth, the best and most definitive and up-to-date documentation you're likely to find. Sounds really good. But grand sentences often sound really good — better than reality even. So let's try checking that against the concrete code and documentation I personally have written. Have I written anything where the documentation describes the code better than the code itself does?

Here's what I could think of during the time it took to brew myself a pot of tea:

I have written code that was not supposed to be used, except by internal unit tests. For instance to get January 1, 1970 instead of the current time. Very useful for unit tests, but do you really want to depend on that kind of thing?

I have written documentation that described only what's common to the current and the the next major version (in Qt, I did that many, many times). Anyone who depended on the documented behaviour got a simple upgrade, anyone who read the source might get trouble, often (more…)

2012-04-04

Popcorn Hour A-300

The Popcorn Hour A-300 is an updated version of the A-110 — a small fanless box to play ISOs and other movies. My work involves such boxes, so I upgraded from the A-110. I still use it with a Synology NAS, an Epson HD projector, a Musical Fidelity M6i amplifier and B&W 804 speakers, and mostly play ISOs ripped with Anydvd.

The A-300 is better than the A-110: The remote control has better range, it doesn't take as long to start playing ISOs, and the user interface is snappier in general.

Its film selection interface remains terrible. It shows less than three film titles per m² of canvas in my case, and navigation is strictly one-dimensional. Up, down, select. A web site built along the same design principles would have wonderful margins and beautiful fonts, but this paragraph would not fit on a 1920×1080 screen.

The screen saver now features animated buzzwords. I call that a feature, because it goaded me to disable the ███████ screensaver. The rest is rather like the old box.

Remarkably, telnetting to the A-300 gives a root prompt.

Update: At first, I didn't notice how bad the sound quality is. I have now played some films with good sound. Ouch is the word.

Update: There are a few bad bugs that Syabas isn't fixing. For example, ISO images without FBI warnings and menus are generally played with the wrong aspect ratio, except the very first time each ISO image is opened. Even cold booting doesn't help.

Update: I bought a FiiO Taishan D03K D/A converter, €33 of high-end audio. The FiiO is a little too up/forward/aggressive for my taste, but it's very, very much better than the A-300's analog output. And Syabas acknowledged the previous bug and provided a workaround: Play in any mode other than fit to screen.