When writing documentation

Tip for developers when writing documentation. Normal people (by which I mean non-developers) do not look at 5000 word blocks of solid text and think "yay! Lots of useful information!".

Diagrams in documentation don't have to convey any illuminating and helpful points. Sometimes they can just be a way of stopping your reader bursting into tears before the halfway point.

Everything that is wrong with web development is perpetuated by the market leading CMSes

As I've said before, I'm not a web developer. I work for a small software house though, and as a result I end up doing a fair amount of web development. It's an experience that always  leaves me wanting to wash. With bleach.

The last couple of years, focus on virtualization has started to move from the big, heavyweight server virtualization platforms like ESX towards virtualization of services or microservices. This is finally starting to realise the promise of SOA in smaller, non-enterprise environments. Docker can run containers on virtualized platforms like AWS to massively simplify deployment and management.

But when you start trying to use this in reality you run into the problem of the CMS. Customers want CMSes - they want to pay for us to set up their site, but have the option to do little tweaks and edits themselves. Web development on the smaller scale end, providing simple sites that are updated a couple of times a month for businesses of up to 20 staff or so; and ecommerce sites for marginal 'run from a bedroom' businesses, small shopfronts etc., is totally dominated by 2 CMSes - Wordpress and Joomla*. There's not a lot to choose between them: both backend into MySQL, both are written in PHP, both have a huge estate of plugins.

The worst problem with web development is that so much of it happens in production. We bemoan 'bedroom programmers' and the amateurish habits of a lot of web developers, but in reality this happens because of the CMS. The CMS stores page content in the database. When you are developing a site for a customer the 'product' you are producing is scattered across template files and database entries. Those database entries are stored on a database engine along with a load of other products. Yes, you can dig them out with database queries, but it's still a mess of jumbled string with no sense of encapsulation. This makes staged deployment impractical**.

This is why everything happens in production, because it's all but impossible to have proper staging and controlled release. All the amateurish shit that happens in web development logically flows from that one place.

Is there an answer? Probably. CMSes backending into MySQL are the source of the problem, especially at this level. Serving from files is faster, more reliable, more scale appropriate and makes it possible to use proper versioning tools. It's only inertia and the availability of plugins that keeps us using them. My favoured approach would be something like Grav running in a docker container, and since Grav has a shopping cart it should be straightforword to do.

Time to do some experimenting.

https://getgrav.org/

https://gravshoppingcart.com/

* Drupal is a bit bigger scale, but suffers from exactly the same problems.
** Yes yes, I know. Vagrant, Ansible, Puppet etc. Very powerful tools that, in this context, do a great job of making up for the design shortcoming that  MySQL backed CMSes don't encapsulate properly.

Android, invisible files, and folders that look like empty files

Ugh.

That took a long time, a lot of poking, swearing, reading stackoverflow, more poking, more swearing, and finally digging around in an open source file manager to find out how they'd done it.

So.

If you create a file on an Android device and attempt to view it with MTP/PTP, and it isn't there, you need to do this:

sendBroadcast(new Intent(Intent.ACTION_MEDIA_SCANNER_SCAN_FILE, Uri.fromFile(f)));

That tells the media scanner that it needs to know about this new file.

Cool. Great. Now, don't do this.

File f = new File(Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES), "MyStuff/");
f.mkdirs();
//THIS! DON'T DO THIS ON A DIRECTORY!
sendBroadcast(new Intent(Intent.ACTION_MEDIA_SCANNER_SCAN_FILE, Uri.fromFile(f)));

Or you'll end up with folders that you can't access from windows via MTP/PTP. They'll look like empty/unknown type files. Just do

File f = new File(Environment.getExternalStoragePublicDirectory(Environment.DIRECTORY_PICTURES), "MyStuff/");
f.mkdirs();

and the folder will appear straight away as it should.

Reading android sqlite db - quick and hacky way

from platform-tools

adb shell run-as uk.co.myco cat databases/data.db > data.db

then sqlite3 the db file

PHP 5.3, Drupal 6, SMTP Authentication, AWS and 'Could not connect to SMTP host.'

I haven't got to the bottom of exactly why this is happening, but if you're trying to get the following combination working

• Drupal 6
• SMTP Authentication 6.x.1.1 with PHPmailer
• PHP 5.3

and you get the error 'Could not connect to SMTP host', you can fix it as follows:

 // Set other connection settings. // LINE 785

  $mail->Host   = variable_get('smtp_host', '') .';'. variable_get('smtp_hostbackup', '');

  $mail->Port   = variable_get('smtp_port', '25');

  $mail->Mailer = 'smtp'; // COMMENT OUT THIS LINE 

I suspect from the debug with the $mail->Mailer='smtp' flag it is sending smtp commands in clear, not starting tls.

Programming and journalism

I was struck recently by the parallels between journalism and programming. I've written a few articles for different publications over the years and learned a bit from the editors of journals about what they wanted the copy to look like. Certain things stuck out as being either similar, or lessons that developers could learn from journalists:

House Style

Every publication has it's house style. Tabloid newspapers use short, declarative sentences, limited vocabulary, and lots of emotive language. Academic journals all prefer their text to be in the third person. Orthography varies too, the house style always defines layout, fonts etc.

Similarly, a development team/organisation often has a requirement for the following:

• bracing style
• naming conventions
• comments / inline documentation

In environments that lack a house style document, I've sometimes written one up by querying the preferred style with the existing team. It makes code easier to read and more consistent.

Editorial requirements

This is more something that should be, than something that is. Code review often tends to be neglected, mainly because project timescales are often tight. For reasons why that is the case, see Frederick Brooks' "The Mythical Man Month". If you follow Brooks' advice of having one person integrating code, they're effectively doing the job that a publication editor/subeditor does - checking that content is formatted correctly, readable, fits with house style and so on, to make a consistent product.

Specialisms and research

Everyone has their specialities. I specialise in Assistive/Care oriented Technology, identity management, web services and a few other less well defined things. I speak Java, Perl, PHP, Javascript, and to a lesser extent Ruby.

But like a journalist called upon to write outside their speciality with good research disciplines and care a developer can do a decent job outside their immediate speciality, or learn a new one rapidly. The economics correspondent can do a decent job of reporting political stories, and the server developer can make a decent job of web development if needed.

Any others?

I'm sure there must be other parallels. I'll update this post if I think of any.

What makes a maintenance programmer

I love maintenance programming. This makes me a freak among developers. If you look at the job adverts, they're all full of 'greenfield development', 'the chance to define direction' and similar phrases. Original development is interesting and fun, but there's a lot to be said for the Sherlock Holmes experience of bug fixing someone else's code. You have to put yourself in their position, learn from their coding style how they're likely to have approached a problem, keep track of complex code pathways to remember where you are. It's extremely tiring because the concentration demands are high, but it's a fascinating challenge.

It's always useful to be good at, and interested in something most other people hate. Anyone got any really ropey legacy applications they want maintaining?