Archive for November, 2014

Validating multiple files in Symfony 2.5

Monday, November 24th, 2014

Symfony 2.5 implemented handy multiple file upload support, e.g. input fields that look like this:

<input id="form_resumes" multiple="multiple" name="form[documents][]" required="required" type="file" />

Unfortunately there seem to be some problems in the Validator component. For example, it’s difficult to require at least one file. Likewise the All constraint doesn’t play nicely with validation groups. Here are a few workarounds.

To require at least one file but not more than three, use the Count constraint in combination with All and NotNull:

This works around a bug where 'min'=>1 is ignored.

If you’re using validation groups, you may notice that the All constraint is not being applied. Here’s how to fix it:

Note line 11: 'groups' => 'Test',

Technically we shouldn’t have to specify validation groups for the All constraint; in fact there seems to be no way to do this in YAML. Hacking it in as an option to All on the PHP side however seems to be working for me. YMMV. And as far as I can tell this last one is fixed in 2.6.

End User Help Documentation: Tricks of the Trade

Thursday, November 13th, 2014

Some internal rumination that I thought would make a nice blog post.  Stuff we’ve learned after a dozen years of dealing with startup software documentation.

Because most software is a moving target, the vast majority of end user documentation is out-of-date soon after it is created.  Out-of-date documentation is worse than no documentation because it adds to, rather than detracts from, confusion.  This problem becomes exponentially worse when maintaining documentation across multiple languages.  It can become a nightmare when resources are limited.

To help prevent the documentation from turning into a problem, consider the following heuristics:

  • Only create a piece of documentation when there is a real need.  Never create documentation for features that are intuitive.  When in doubt, leave it out.
  • A picture is worth a thousand words.  Use screenshots and a minimal amount of text.
  • Avoid full-screen screenshots.  “Narrow” screenshots are easier to understand and much easier to maintain as the software evolves.  That said, leave enough surrounding space so that the user can recognize context.  (A screenshot of, for example, a single widget is like trying to ask someone to make an identification from a picture of an eyeball..)
  • When possible, describe a feature in general terms rather than specific steps.  This approach will have more “staying power”, meaning that the documentation is less likely to change even if there are small changes to the software.
  • Create a style guide to help keep the documentation consistent.  Especially important when multiple people are working on the documentation.
  • If resources are limited, only translate “proven” documentation or documentation that is demand.  Services like Freshdesk have “Was this answer helpful?” features.  I recommend only translating documentation that gets at least one up vote, or issues for which we get at least two support requests.

And of course:

  • Whenever possible refactor for usability rather than write even a line of documentation!

If you’re working on documentation and have come across this post, I feel for ya..  Keeping the scope as small as possible will bear you in good stead.