Better “How To” development guides
Posted on 19 January, 2019
This post briefly complains about the content of a Medium article; to be clear, the complaints are general about this type of article, and aren't intended to be a dig at this particular article or its author.
I just finished looking at a Medium article on GUI Python interfaces on Mac — and it's irritated me.
There's a tendency with these kind of "how to" articles, when introducing a new topic for (presumably) inexperienced developers, to launch into a long list of command line instructions with a few screenshots. And there is nothing wrong with that.
What irritates me though, is when there's no context given. No explanation as to what it is that the instructions are achieving, or why. The linked article essentially boils down to:
- Install some dependencies (7Zip, LibClang, XCode, CMake)
- Create a virtual Python environment
- Install Qt
- Install PySide2 (download the source and compile)
- Run a test
At no point — from my read-through — is there any attempt to explain why the author is doing any of these things. This is actually the first part of a series, but there's not even an explanation at the top. How hard would it be to add at the top:
In this part 1 we'll install all the software and packages that we need, and then in part 2 we'll look at how to use them to build a custom GUI interface.
Add that note at the top of the page, and some brief comments for each package as to what it does and why it's being installed (especially with 7Zip, which is only being installed to un-archive LibClang — how about if you have another archiving tool installed? Will that work? Shouldn't we at least mention this in passing?) and you'd end up with an article that's more engaging, more informative, and would probably lead to a far higher conversion rate to reading the second article.
I don't consider myself to be a coding newbie, and I don't necessarily need some of this information, but if you want to make your content available to all, you need to write it to an "intelligent beginner" audience.
Disclaimer: I was too irritated by the above to read the second article, so only realised after publishing this that there isn't (at time of writing) a second part.
