The most important single task of a developer is to protect a user’s work from accidental deletion.1 Alas, Daniel Jalkut has put MarsEdit users out on a very thin ledge, where it’s very difficult to go forward or back without falling off the ledge and losing huge amounts of work.
What’s the issue? you ask. Jalkut loves his users and is one of the good guys. He’d never do that to us.
Jalkut’s good intentions are not in doubt. If it wasn’t for MarsEdit there would be no way to post on WordPress from macOS except via the clunky WordPress interface which is anything except a writer’s tool (it’s impossible to forget the technology with all the options displayed at all times for publishing date, publishing status, categories, slug, tags, revisions, discussion, comments, trackbacks even without third party basics such as meta-description and social sharing options, let alone Yoast style post semantic SEO analysis).
The issue man. What has Jalkut done?
As I mentioned, it’s the save routine. There’s two ways to save a WordPress post which has been published in MarsEdit, either on the server (within the WordPress interface) or within MarsEdit.
If the version on WordPress is more recent, then one can just click command-R to refresh the weblog post and get the most recent version before editing in MarsEdit. Or one can refresh the whole weblog with shift-command-R. Or if the version is more recent on MarsEdit one can publish to WordPress from MarsEdit and then take it over on WordPress for final tuning (media management is much more robust, naturally, from within WordPress, third-party content modification plugins like FV Player for instance, can only run properly on the server).
Sounds great, no?
Not so great. There’s no notification when opening up a post in MarsEdit that the version on the server is more recent. Hence when publishing the modified post from MarsEdit, any work you or a colleague did on that post or page will be lost. Fortunately WordPress offers revisions by default so it’s likely you will be able to recovery your work. It’s a pain but there is visual diff built straight into WordPress to allow you to see what’s changed and what’s been lost. In the worst case, you can copy two versions and manually merge them in a text editor like iAWriter (Markdown) or BBEdit, Smultron or CodeRunner (HTML).
Overwriting data by default without warning
Even worse, if the version on the server is out of date and you have a more recent version in MarsEdit, Refresh will simply overwrite that post’s changes. Still worse, Refresh All will overwrite all data which may have been changed in MarsEdit.
I’ve scoured the MarsEdit preferences (there’s ten pages of them, happily nicely divided by functionality group) for a place a checkbox to check versions. I couldn’t find one.
How do I protect my data?
At this point, there’s no way, except via strict workflow. My recommendations are twofold:
- After you have published an article on WordPress, don’t edit it any more in MarsEdit. This is difficult as MarsEdit is generally (media apart) a much better writing environment for major changes. If you do decide to do so, do so consciously thinking about where the most recent version of the changes are before opening or refreshing the post.
- Do not leave edited articles open in MarsEdit unsaved on the server. If you have to stop working on an article, publish the changes in progress before leaving it, even if you are not completely finished. That way at least there will be a recent revision within WordPress as a fallback.
What I often do with an article which has already been published is copy the Markdown out to iAWriter and edit it there. The preview is better, the code highlighting is better and there’s no chance of losing data.
None of these worries about lost data apply, happily, to local posts which have never been shared to the server. You can rely on MarsEdit to manage unpublished, draft posts in the hundreds.
How could Jalkut ensure that writers don’t lose content?
What MarsEdit should do when opening up a local copy is checking online to see if there have been changes there in the meantime and alert the writer that there is a conflict with the save dates. Save dates are complicated by time zone, daylight savings time, micro-differences (usually seconds but can be a minute or two if clocks are wrong) – but those are known problems and have solutions.
If MarsEdit is offline (the writer is working in an airplane, we have a client who uses MarsEdit for just this purpose, I could see writing in MarsEdit when I am away in the woods offline), then before publishing the revised article MarsEdit could check for a conflict in save and creation dates and alert the writer that there is a possibility that s/he is overwriting content on the server.
Ideally there would be some kind of diff reconciliation or at least preview, but that’s a further step and quite a bit more work. Just alerting the writer that there is the strong possibility of losing content would be a very good start. In the alert, Jalkut could recommend better workflows (a documentation article on his website, see below) to avoid getting these notifications.
Something, anything, is better than just overwriting data.
Similar Sins: Broken Update Notifications and Hidden Credentials
Jalkut’s update routine is no great shakes either. I was having issues with MarsEdit 4.6.3 uploading images. It turns out that MarsEdit v5.0.5 solves those image upload issues, with no configuration changes. Check update does not tell me about that v5.0.5 update. I have even bought and paid for v5 and Jalkut still won’t tell me that I could update the copy of MarsEdit on this computer. There’s very little visual difference (I’m probably running v5 at home).
While we are talking about major inconveniences for the user – setting up a self-hosted weblog in MarsEdit is a great deal more difficult than it needs to be. Jalkut hides the login credentials under the Blog menu. Blog menu is the right place but to see the login/password credentials a writer has to press option while clicking the Blog menu. Totally bizarre. There’s zero documentation about this credentials issue. A very technically savvy client to whom I recommended MarsEdit ran into this issue and was unable to hook his weblog up. Even after two hours of hitting his head against the technological wall he couldn’t post. I asked Daniel about why he hides credentials from users?
Oh, he said, most users are using WordPress.com and don’t need to enter their credentials.
How the rest of us are supposed to figure out how to publish to our weblogs is a mystery to me. I asked Daniel why this isn’t in the documentation.
Well if anyone is having any issues, they can just write me.
Good documentation saves users time (and the developer) time
It’s true Daniel answers his emails promptly – he’s a nice guy. But FFS some documentation would be helpful. The only people really using MarsEdit are geeks (there’s way too many preferences, it’s really hard to set up) and geeks like to solve their own problems. Usually we start without the manual but decent technical documentation is a huge help when running into an issue. Even if a project doesn’t have great documentation, many open source projects at least have GitHub issue trackers, where one can see other developer-type users complaints, solutions and workarounds.
MarsEdit as a private project doesn’t even have the GitHub issues tracker. It’s a black box, with no user forum and no documentation. Bad news.
These little issues, caring for the user experience, are so important. It’s frustrating that such a good and well-intentioned developer seems to be deliberately neglecting user experience and new user experience.
These notes about new user experience should be useful to more than Jalkut. Any developer should care deeply about:
- onboarding
- data preservation
- documentation
Let’s leave MarsEdit and look at a few more examples of the importance of documentation to software value, both for the publisher and the user.
The role of documentation in the success of Affinity Photo, Easy Digital Downloads, DaVinci Resolve
There are many software which I’ve chosen as much for the quality of the documentation as for the quality of the code. Two examples which come to mind are Affinity Photo, Affinity Designer, Affinity Publisher and Easy Digital Downloads. Affinity’s applications are first rate in 2023. When they first came out though Affinity Photo was part of a half-dozen Photoshop wannabes. What made the difference for Affinity was that creator of Affinity Photo (name) published a series of hundreds of bite-size videos explaining how to use the functions in Affinity Photo.
Instead of frustration at the differences from Photoshop, users could learn how to use the similar but often better (benefiting from two decades of software improvements) methods in Affinity Photo. Those documentation videos gave Affinity Photo an edge with users and gradually momentum in a crowded and muddy marketplace. Most of the world is very happy to have a viable alternative to Adobe in static publishing.2
In the case of Easy Digital Downloads, founder Pippin Williamson was no design genius. His many ecommerce and membership plugins respected WordPress design conventions but always had a boxy and awkward look to them. What EDD and Pippin’s other projects had going for them was a good API and very copious documentation. If we had issues with other ecommerce solutions even figuring out how they worked, let alone how to use them with the API, with EDD there was always great detail about the functionality that was there. Sadly, Pippin burned out, stopped improving EDD in deep ways (no third party EDD plugins, we’d built one and Pippin wouldn’t take it on) and sold it on. Thanks though to the great documentation and structural simplicity of EDD, we are able to continue to use EDD on Foliovision.com (heavily modded) and other client sites.
We paid Sandhill Development thousands of dollars over the years for our eventual lifetime licenses so it’s a very good thing the software remains usable. What persuaded us to make the investment, again, was mostly the documentation.
Developers, do not neglect your documentation like Daniel Jalkut. Like him, you will undo your thousands of hours of hard work, simply by failing to publish adequate documentation.
-
One might argue that these days the most important single task of a developer is to protect the security of a user’s work/data. I would say that’s a secondary task as if the work is not saved properly in the first place, security is a secondary concern. ↩
-
Blackmagic’s DaVinci Resolve provides a better alternative to Adobe for motion. Finally one can create in a world without Adobe and without Apple (very unreliable partner, where is Aperture, where is FCP Studio), thanks to Serif and Blackmagic Design. Incidentally the DaVinci Resolve manual is 4000 pages and free. There is also a 400 page free guide called The Colorist Guide to DaVinci Resolve 18. Again documentation won the day, in a field where complexity reigns (video editing, advanced grading tools, sound design, FX creation). In the case of DaVinci Resolve, it’s the reasonable pricing without crazy annual upgrades (Avid) or subscriptions (Adobe). Apple proved themselves to be an unreliable partner and frankly even in v10 FCPX is an under featured and underpowered iMovie Pro in comparison to the original FCP Studio or to DaVinci Resolve. ↩
Alec Kinnear
Alec has been helping businesses succeed online since 2000. Alec is an SEM expert with a background in advertising, as a former Head of Television for Grey Moscow and Senior Television Producer for Bates, Saatchi and Saatchi Russia.
Leave a Reply