Article Submission Guide
Quality is our top priority for articles published on Software Ascending: quality of content, quality of writing, and quality of form. This page describes the key criteria an article will have to meet before we publish it.
If you’ve got an article you want to submit but missed a few of these points, or maybe writing just isn’t your thing, don’t worry about it: we’re happy to work with you on editing and revising and may even be able to provide a ghostwriter to help get your story out. If your article is a good fit for Software Ascending and you’re willing to work a little on it, so are we.
The rest of this article describes our guidelines for high-quality content on Software Ascending.
Proofread, edit, and revise
First and foremost, we care about quality. It’s hard to take an article seriously if it’s riddled with typos, missing words, or egregious spelling mistakes. Take the time to carefully read over your article before you submit it; make sure it is clear and contains no obvious mistakes. We can work with you to clean up and improve an article, but a sloppy submission signals to us that you’re probably not interested in taking the time to get it right.
Topics and Content
Software Ascending targets experienced developers. We’re looking for articles that rise above the noise of three-minute intro articles, hot takes for junior developers, boot-camp style quickstarts, and the like. Those kinds of articles can be great for new developers, and supporting new developers is crucial to the health of the field; but the Web and Medium, in particular, is flooded with these articles. What seems to be missing, the gap we’re trying to fill with Software Ascending, is a body of high-quality articles that appeal to, and are useful for, more experienced developers.
There’s no specific list of topics that are in scope for Software Ascending. Write about what you find interesting; write about your “Ah-ha!” moments and lessons learned; write about the principles you’ve discovered and developed in your tenure; write about the stuff that makes you excited to keep coming back to your terminal and writing (or rewriting) code day after day.
Length
We understand that a lot of readers have short attention spans (we’re no exception). We also know that a lot of developers are reading articles on their lunch breaks, while projects are building, or while walking to the bathroom. An hour-long read is going to be hard for most people to get through.
However, it’s also going to be hard to get the kind of depth that our readers are looking for in a quick three-minute read.
A five- to fifteen-minute read is a good target, but you should focus more on creating content of value, rather than worrying about a specific length.
Language and Tone
At this time we can only support English language content, limited by the languages known to our editors. We don’t have a strong preference for what locale you use, just be consistent and avoid any regional terms or phrases that wouldn’t be generally understood by a majority of English speakers.
The tone and language should be casual-professional like you would use with your direct manager. Profanity isn’t strictly out of the question, but it should be used sparingly and inoffensively, or simply not at all.
Jargon is generally fine; this is a technical publication for experienced technical people. Terms, expressions, and acronyms that are somewhat more obscure or specialized (i.e., likely to be unfamiliar to some target readers) bare a quick explanation.
The most important thing about the tone is that it is constructive, not condescending, arrogant, aggressive, or insulting. You can be critical, explain risks and problems, describe what’s good about your ideas and suggestions, without disparaging anyone. Don’t assume anyone else is stupid, don’t assume you’ve thought of everything, or that no one else has thought of the same thing as you. Avoid absolutes. Present your case, make your arguments, and leave room open discourse.
A few phrases you might want to strike from your repertoire:
- “Such-and-such considered harmful.”
- “Obviously…”
- “Of course…”
- “Why would you…”
- “Why wouldn’t you…”
Pandering, Disclosures, and Affiliate Links
Please don’t ask for claps or follows; if people like your work they will clap for it and follow you. If you have other articles or resources (created by yourself or others) that are actually relevant to the article, feel free to link to them. If you have your own external website, it’s fine for you to have a very brief mention and link at the end of the article, but the overall tone and feel of the article should not be one of self-promotion: let your work stand on its own.
We also ask that you don’t include a personal profile or biography in your article; as the author, your medium profile will be linked automatically and provides a place for you to provide a brief profile.
Similarly, we are not out to promote third parties: if you have an affiliation with any entity you’re writing about (professional, quid pro quo, or even volunteer), at a minimum disclose the nature of your affiliation at the beginning of the article. We will be paying extra attention to look for any bias in the article that may mislead readers.
This is not to say we won’t publish your article: if you work for Company X and use your knowledge to write a useful guide for how to use their software and why you might want to, we’re happy to have that. But if you’re writing is overly promotional, is little more than a sales pitch, or is misleading in any way, we won’t take it as is. The key is to be honest, balanced, and unbiased.
Linking to sites for commercial entities will also draw careful consideration from editors. Again, this does not mean you can’t do it, it just means you need to do it appropriately: linking to more information about the thing you’re writing about is fine; linking to promotional material for something that’s only tangentially related to your article is probably not.
Structure
Title
No clickbait. Not even tongue-in-cheek clickbaitesque titles; they’re just not funny anymore.
Your title should be compelling, but not at the expense of clarity or accuracy. Don’t oversell or over-promise.
Also keep in mind that a long title will be truncated in previews, web cards, emails, etc.
Abstract
Your article should start with a brief abstract: a few sentences explaining what the article is about and why someone would want to read it. This is your chance, likely your only chance, to hook your reader, convince them that it will be worth their time to continue reading.
Make sure you also set your article’s summary in the publication settings when you submit your article. This is generally similar to your abstract, but possibly even shorter (if it fits, using your abstract verbatim is fine)
Conclusion
Your article should also wrap up with a quick conclusion that very briefly reviews the main points of the article. A conclusion helps with comprehension and especially retention, and gives the article a more polished feel.
Sections and Headings
Dividing your article into sections is generally a good idea for all the but the shortest articles. Don’t overdo it; a few sections to organize your article and help your reader understand what they should be focusing on is enough. This article, for instance, is probably using more sections that most articles will really justify.
You may feel compelled to impose a hierarchical organization on your article, just like you organize your code. Try to resist this urge. Medium’s formatting only provides two levels of headings, and they really aren’t all that distinct. For the most part, it’s generally best to stick with a flat organization using only level-one headings (the larger ones).
Look and Feel
We want you to write with your own voice, but the publication as a whole should have a certain amount of high-level consistency to its look and feel. The following sections provide a few key points.
Numbers
In prose (as opposed to code, mathematical, or financial contexts, for instance), numbers should generally be written out in words, not digits.
Abbreviations, Acronyms, and Initialisms
Generally avoid unnecessary abbreviations, though common and acronyms and initialisms are fine (e.g., “JVM” in a java context, “NSA” in a security context).
Feel free to use “e.g.” and “i.e.”, but make sure you’re using them correctly: “e.g.” means “for example”; “i.e.” means “in other words”.
Code Snippets
Code snippets are really useful in articles about code, but can easily go awry. Focus on brevity and clarity over cleverness and best practices that aren’t actually related to your point.
Code should always be correct, but it doesn’t need to be complete: it’s better to omit some details that would distract from or obscure the relevant pieces then it is to include them for the sake of presenting compilable or executable code. If necessary, use comments to indicate where code has been omitted, as in the following example:
Breaking your code into multiple snippets can be useful to keep each snippet better focused, just make sure there is enough context that the reader can understand how the pieces work together.
Given that most snippets you include should be brief, we generally prefer good looking images of the code to marked-up text or text-based embeds like gists. For image-based code snippets, use carbon with our predefined settings. You can turn on line numbers if you want to refer to specific lines in your article.
If you have code that you really feel should be presented as text instead of an image, an embedded CodeSandbox or CodePen is preferred (in that order) for supported technologies, RunKit is also acceptable for NodeJS code, and Repl.it should be used for any other supported code. As a last resort, embed a gist if none of the other platforms will work for you.
Providing a complete reference project is a great way to give more details, pull all your code snippets together in context, or provide additional materials for readers to explore. These projects should generally be posted as public repositories on GitHub or GitLab with a link provided in the article.
Images
It’s no secret that images catch people's attention; a featured image, usually a full-width header image, go a long way toward giving your article some polish. Images within the body of the article can be helpful in delivering your message, but don’t overdo it. While your header/featured image might be more symbolic, images within your article should generally be directly relevant and should be used to augment your message, not simply for decoration.
Don’t use images you don’t have permission to use and make sure you’re giving proper attribution as required by the license. If the rights to the image are owned by you, attribute it as such.
As with your tone and language choice, images should be appropriate for a professional workplace. In addition to setting an appropriate tone for the publication, keep in mind that people will often be reading your article at their desk in view of their manager and co-workers; they’re not going to keep reading if they scroll down and find a blush-worthy image.
In particular, we’re sensitive to any objectification of people’s bodies within the publication; there’s no need for it in a technical article and it fosters undesirable attitudes and behaviors in an industry that is already rife with gender biases, discrimination, and harassment. So if you’re writing about image processing, for instance, you’ll have to find a test image other than “Lena”.
