how to write tech articles

PASS Data Community Summit

Watch sessions online for free

14-17 November

How to Write an Interesting Technical Article

To write a technical article, one just surely needs technical knowledge. Well, no. The very best technical writers take enormous pains to present information in an interesting way. This isn’t a mysterious art at all, and the technique can be learned just as easily as square-dancing. Journalists are taught the technique though they often forget. We give just a few pointers.

Why, one wonders, should technical writing be so boring to read? The writers within the IT industry almost try to make a virtue of their ability to repel the readers.

Part of the problem is that there is no best-practice to emulate. We have a lot to be ashamed of in the way we communicate. Another aspect of the problem is that a lot of writing is not even intended to convey meaning; instead, it is a technique for obfuscating technologies, in embellishing the importance of the writer, or in conveying the vague impression that a particular technology is splendid.

Writers like to suggest that they possess a mysterious art. In truth, it is not a matter of talent, but craft. Nobody is born with the gift of welding, busking or programming: all crafts are learned through graft, sweat, and self-criticism.

Capture the readers’ interest as soon as possible

The commonest mistake is to write a dull first paragraph. Most readers will not tolerate such a thing. Even in technical writing there is no excuse for that.

Any aspiring author who is writing in English need do no more than read the first paragraph of the novel ‘Moby Dick’, by Herman Melville, to see the perfect way of starting.

‘Call me Ishmael. Some years ago- never mind how long precisely- having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world. It is a way I have of driving off the spleen and regulating the circulation. Whenever I find myself growing grim about the mouth; whenever it is a damp, drizzly November in my soul; whenever I find myself involuntarily pausing before coffin warehouses, and bringing up the rear of every funeral I meet; and especially whenever my hypos get such an upper hand of me, that it requires a strong moral principle to prevent me from deliberately stepping into the street, and methodically knocking people’s hats off- then, I account it high time to get to sea as soon as I can. This is my substitute for pistol and ball. With a philosophical flourish Cato throws himself upon his sword; I quietly take to the ship. There is nothing surprising in this. If they but knew it, almost all men in their degree, some time or other, cherish very nearly the same feelings towards the ocean with me.’

See? Did you notice the hammer-blow of the sentence that starts ‘Whenever I find myself going grim about the mouth….’, after the simple first sentence? The way it reads as if he was really speaking directly to you? Did you notice the ingenious rhythms of the sentences wrought through the clever mix of syllables? No? It’s only because you aren’t analyzing why some communication works, and why others don’t. It wasn’t just talent by Herman Melville, it was as calculated as putting up a pair of shelves.

Ah, you say, that’s a novel, easy, what about a text book? No problem, Read this. It’s the start of ‘The Age of Scandal’ by TH White.

Well, we have lived to see the end of civilisation in England. I was once a gentleman myself. When I was an undergraduate at Cambridge, the Master of a college was a fabulous being, who lived in a Lodge of breath-taking beauty and incalculable antiquity, tended by housemaids, footmen and a butler. There he consumed vintage port, wrote abstruse treatises if the spirit moved him, and lived the life of an impressive, cultivated gentleman. Such posts were among the few and noble rewards rightly offered to scholarship by the civilisation which then existed. When I last stayed in Cambridge, I lunched with two Masters of colleges. Both of them had to help with the washing-up after luncheon. There was a comic story current shortly after the Hitler war— one tried to think that it was comic. It said that there was some conference or other at Lambeth, thronged with archbishops, cardinals, patriarchs, moderators and so forth. The Archbishops of Canterbury and York were seen to be in earnest consultation in one corner of the room. Were they discussing a reunion with Rome or a revision of the Prayer Book? Thrilled with the ecclesiastical possibilities of such a meeting, one of the stripling curates managed to edge himself within earshot of these Princes of the Church. They were discussing whether it was worse to wash-up or to dry-up.

A poker-faced, TH White, in mischievous mood, starts with a shock, and then uses his facile virtuosity to attempt to justify the impossible. He then does an elegant pirouette into the comic. The reader is jolted into attention. This is going to be no ordinary History book.

So what is the message from these examples? The masters of literature use spoken language, There is no separate convention for written prose. They hit you with fresh ideas and subvert your prejudices to get your interest. They jolt you into attention. Don’t worry, if you can’t be brilliant, then be clear and simple so that your readers will be grateful, and continue to read.

Keep things brief

Think, for a moment, of those things that you’ve read that have made the most impact on you. Short, eh? A good writer will rework material constantly to refine it and presume less on the patience of the reader. There is a well-known adage in the IT industry that the average manager can read just one side of A4 before his attention wanders. I’m surprised, from my own experience, that it is that much.

Work to a strict framework but then remove it

When a house is built, then the scaffolding is removed. Often, in technical writing or academic work, not only the scaffolding is left, just to prove that the house was properly built, but the cement mixer is left in the garden. Essays are littered with headings like Introduction, Summary or Conclusion. Ironically, they often aren’t.

All writers need structure. I once called in to see Duncan Kyle, the novelist. His study wall was a sea of notes, pictures, and references pinned everywhere as he worked on his next action thriller. Months of work preceded the typing of the first draft. PG Wodehouse famously pinned his stories around the wall of his study at a height commensurate with the quality of the page. He worked at them until they all reached the ceiling.

I like to use the old schoolmasters’ trick, where you start by filling in a grid marked ‘What?’, ‘ Why?’, ‘Who?’, ‘Where?’, ‘When?’, ‘How?’, and then sequencing the various ways that you answer those questions, and developing the structure from these ‘nuggets’.

Notice that scaffolding conforms exactly to the shape of the house. You should never use a standard shape or put the scaffolding up before you’ve designed the house.

Periphrastic perambulations are anathema

Keep words short where possible, but pop in the occasional polysyllable just to help the rhythm of the words. With technical writing, you must never use abbreviations without defining them, even if they are well-known in your immediate circle. When using a highly technical sentence, a useful trick is to follow it with the same message written in simple English. That gathers up all your readers, whatever their prior knowledge, to lead them onwards. Be sympathetic with all those keen and interested readers who are not native English speakers. They will not thank you for show-off words as in the heading of this section.

It is said that the effect of eating too much lettuce is `soporific.’ I have never felt sleepy after eating lettuces; but then I am not a rabbit. They certainly had a very soporific effect upon the Flopsy Bunnies!

Beatrix Potter, at her majestic peak, gives the perfect example in her ‘Tale of the Flopsy Bunnies’. How poorly it would have read without the word ‘Soporific’.

In the fourteenth century, John Wycliffe made the first English translation of the bible in the spoken Yorkshire dialect of the common man. Its effect on English literature was far more profound than that of Shakespeare. If you can convey complex messages that simply, why feel the necessity to make anything more complex?

In the bigynnyng was the word, and the word was at God, and God was the word. This was in the bigynnyng at God. Alle thingis weren maad bi hym, and withouten hym was maad no thing, that thing that was maad. In hym was lijf, and the lijf was the liyt of men; and the liyt schyneth in derknessis,and derknessis comprehendiden not it.

Convey the emotion

When writing in the academic style, we are trained to write like a disembodied entity, devoid of all emotion. This is why academic essays are never read for pleasure. All literature, comic or tragic, is about the clash of emotion. To write well about technical subjects, one has to be interested in the subject and aware of the human struggles and mistakes behind any technology. The effect is subtle but profound. If your heart isn’t in it, you should never go near the keyboard.

Here is LTC Rolt, the engineering historian, with a classic paragraph from his book ‘Red for Danger’ on the history of accidents on Britain’s railways.

One of the most tiresome and menacing of the early experimentalists (in the early railways) was Doctor Dionysius Lardner, a character strongly reminiscent of ‘Beachcomber’s’ Doctor Strabismus. That he enjoyed for a time a great reputation as a railway expert was due to the fact that he was one of the first masters of the art of blinding the layman with science, but that he was able to impose upon the railway companies themselves is more mysterious. Speaking against Brunel’s proposal to construct the Box Tunnel on the main line of the Great Western Railway with a continuous gradient of 1 in 100, the Doctor pronounced that if the brakes of a descending train were to fail as it entered the tunnel it would emerge at a speed of 120 miles per hour, a velocity at which no passenger could breathe. Brunel pointed out that the Doctor had failed to take into account either frictional or wind resistance and that the speed would in fact be only fifty-six miles per hour. But the savant’s self-esteem remained unshaken. With an inconsistency surprising in view of this first gaffe, we next find him pontificating against the broad gauge on the grounds of the increased ‘atmospheric resistance’ of the wider vehicles. It is obvious that a man of the calibre of Isambard Brunel knew perfectly well that Doctor Dionysius Lardner was a pompous fraud and yet for some extraordinary reason the Great Western Company gave him the use of an experimental train and the liberty of their tracks. For the two months of September and October 1838 the Doctor’s train was at large on the main line to the extreme hazard of the regular services. It was asking for trouble and, sure enough, it came. On September 26th George Henry Gibbs, promoter and director of the Company wrote in his diary: ‘the eight o’clock train ran into the experimental train and injured three of the carriages very much’. Did the Doctor apologize? Did the Company order him off? Not a bit of it. He seems to have assumed the rights of royalty and wrote the Great Western board a furious letter which Gibbs described as ‘Very improper’. A month later the experimental train was again involved in a collision. Fortunately, or perhaps unfortunately from the Company’s point of view, the sage was not on board on this occasion and it was his unfortunate pupil who paid the penalty. He was killed on the spot.

Cite and acknowledge sources

The technical writer must behave with exaggerated courtesy. For some reason, humanity strains to give a compliment, and to acknowledge good work in others. Criticism seems more natural. The author should cite all quotations and sources of any information as he would in an academic treatise. Not only do the authors appreciate it, but the writer of the article shows that at least he has done his homework. Any article used or even glanced at in the preparation of some writing should be listed at the end of an article as a source. it costs nothing to thank anyone who helped with the article as well.

Subscribe for more articles

Fortnightly newsletters help sharpen your skills and keep you ahead, with articles, ebooks and opinion to keep you informed.

Developers: The Why and How to Writing Technical Articles

by Goodness Kayode

I posted a small broadcast on the need for technical articles to add to my publication on a Whatsapp group of over 200 developers. The response I got prompted me to write this short article. I have found out that many developers do not find it important to write articles and I believe it is not right.

As if I knew many developers wouldn’t have technical articles, I decided to add the last paragraph to the broadcast. To my surprise several developers messaged me that they needed help on starting to write technical articles and that is why I decided to write this quick article.

To start with, it takes a lot to come out with awesome content. I know this is what puts many developers off. But at the first part of this article, I will talk about the benefits of writing technical posts.

Build Your Portfolio

One key thing about writing technical posts is that it can help build your portfolio as a developer. And it gives you an ample opportunity to be seen as skilled at what you do.

Another thing I feel has helped developers like Prosper Otemuyiwa and some others is the fact that no matter how little the tutorial is, they make sure they do something.

Help Newbies

Before you got to the stage you are right now, some people helped you get there through videos and articles. That is enough reason to write contents for other people to learn from.

The more you write on a particular thing, or let me say the more you teach a particular thing, the better you get at it. Writing technical contents may involve you writing about an application you just built that gave you a lot of stress that you don’t want other developers to go through. Or you just learned a new thing and you want the world to know what you have learned.

Doing the above mentioned, helps you build confidence in what you know.

Yea! Money is very important and you don’t get it by sitting and not doing anything that will add to someone’s life. You can get paid for writing technical contents. But before you get paid, you must have written some interesting content as samples.

I know a few companies that pay for technical write-ups. One is Scotch Development . This is not because they have a lot of more to waste, but because they believe development is a lot easier when you have the right content to guide you.

One of the things that makes me glad is the number of views I get on my articles. I wrote an article on [ React, Babel,webpack and Webpack 3.0 ] and Codementor alerted me on twitter that I have had 2,000 views. And I became proud of myself.

I think seeing people reading your content and learning from it should be a plus to you.

Limited Restrictions

Few people invest their time in writing technical articles and it gives more opportunity for people who write to have an edge to getting something a lot of people apply for.

Auth0 opened their web application for applying as an Auth0 Ambassador. One of the fields for the application included that one could attach links to write-ups written. That should ring a bell .

HOW DO I START?

I get asked this question every time I talk about writing technical articles. In this article I will just explain how to get started based on my experience and other posts I have read on getting started with writing technical articles.

• Believe you can

You don’t have to be the world greatest developer to write an article. You can always write an article on what you are learning presently.

But the first thing is to believe in yourself.

2. A Little Step but Great Beginning

Many developers get confused at this point because they feel “What can they write that will impress people?” But I will always say “Start with something small.”

My first post on medium was PHP: BEYOND BUILDING WEBSITES and it was not a real ‘techy’ kind of article. I wrote it just to have something out and people encouraged me by recommending it. And I got an invite to become a writer on a medium publication.

That was the little step I took and now I have more tutorials out on Scotch Development , Codementor , Medium , @dev.to and so on.

Just give it a try.

3. Learn New Technology

The best way to have something to write on is to learn new technologies. Learn new frameworks you were not asked to learn and write on it.

Recently, I saw there was a new JavaScript framework without any tutorial on it. When I went through the documentation I found out how light and awesome it was.

So, I made a tutorial on it and some popular JavaScript Twitter users got to know about the article and kept re-tweeting and I kept getting more views.

4. Topics are around you

Some developers feel topics are the main issue. To be sincere, it is not as the quality of content is the most important thing. You just have to be sensitive.

I know Scotch Development has a section on their websites where you can get ideas of tutorials you can write on. Check it out here .

Basically, there are no new topics. What you have are differences in content most of the time.

5. Know Your Niche

To be successful at this game, you have to carve a niche for yourself. If you know you are awesome at building web applications, stick to it. And if it is mobile development, Artificial Intelligence, ML and so on, stick to it.

Because if you make mistakes that you shouldn’t have made while writing a tutorial, people will take you as a confused individual.

6. Be Unique In Your Writing

When writing, you have to be as simple as possible and free at the same time. Write your articles like you are explaining something to another developer and you want them to understand in simple terms.

You could always include funny GIF images, short videos, screen shots and so on to keep your reader reading.

7. Get Feedback

Brother! Sister! Don’t think you know everything. You will only be shooting yourself on the leg. Ask for comments and be open to criticism because you cannot avoid it.

Let people be able to talk to you about something not being clear to them via e-mail or Twitter.

8. Don’t Stop Writing

I shouldn't have added this but let me. Don’t stop writing once you start and maybe face a lot of criticism that you don’t know anything.

Work on the corrections and write more and it will pay.

I believe you must have gained something from my little mind-speaking article and I will be glad if you can share your thoughts with me on Twitter @goodnesskayode

I will love if you could read some of my articles on Scotch.io , Codementor , LinkedIn and Dev.to .

If this article was helpful, share it .

Learn to code for free. freeCodeCamp's open source curriculum has helped more than 40,000 people get jobs as developers. Get started

DEV Community

Posted on Dec 3, 2021 • Updated on Feb 17

How to write a good Technical Article

As a developer, I have made $500 in the last month writing Technical Articles.

Below are some of the things I have learned about writing a good technical article.

What is a technical article?

A technical article is an article that is used to inform, instruct, or direct a specific audience on how to do something.

To write a good technical article, there are some things you need to get right.

1. Come up with a good structure or layout.

The format of an excellent technical article includes:

• Introduction

A title should be a headline that demands attention and should have keyword combinations that reflect what the article is about.

The introduction should describe the problem and the solutions that the article will cover. Ensure that the introduction lets the reader know what the article is all about.

In the body part of the article, describe the problem and the solution in detail. Try to tell a story. The story should keep the reader engaged at every step. Make a list of your main points. Then progress from one point to another logically to lead to a conclusion.

The conclusion should essentially include a summary of all the main points mentioned in the body.

2. Do a lot of research.

Writing a good technical article is challenging because it can take a lot of your time and often requires doing a lot of research.

Doing research when writing a technical article will help you understand the problem you are trying to solve and the solutions you can come up with.

The research will also help you understand your audience and the message you are trying to deliver to them.

3. Know your audience

Knowing your audience when writing a technical article is very important because:

• It helps you to make decisions about what information you should include.
• It directs you on how you should arrange that information.
• It helps to know what supporting details will be necessary for the reader to understand what you are presenting.

Keeping your audience in mind will help you organize your ideas and how best to support your argument.

4. Use examples

Use examples to help your audience better understand and relate to key points of the technical article you are writing.

Examples can be in the form of screenshots or code snippets.

As a technical writer, examples can serve as evidence to support your general claims or arguments.

5. Read other technical articles.

Reading other technical articles will help you get inspiration and give you ideas on writing better articles.

You can get inspiration by reading some of the technical articles I have written and published so far.

This article shows you how to export Stripe payments data from Stripe to Postgres for deeper queries and data analysis for visualization.

https://arctype.com/blog/stripe-payments-sql-postgres/

This article directs you on how to use Stored procedures to allow access to some parts of a table in a database while denying direct select, insert, update and delete operations against the table.

https://arctype.com/blog/stored-procedures-in-sql/

Top comments (2)

Templates let you quickly answer FAQs or store snippets for re-use.

• Education Computer Science bachelor
• Work Software engineer
• Joined Jul 25, 2018

Could you elaborate more on how did you earn this money?

I mean, I am interested in writing technical articles but which are the platforms/apps paying you for writing?

Any advice is appreciated!

• Email [email protected]
• Location India
• Work Full Stack Developer
• Joined Apr 6, 2020

Here you go: github.com/malgamves/CommunityWrit...

Are you sure you want to hide this comment? It will become hidden in your post, but will still be visible via the comment's permalink .

Hide child comments as well

For further actions, you may consider blocking this person and/or reporting abuse

🚀Creating a resume builder with NextJS, Trigger.dev and GPT4🔥✨

Eric Allam - Nov 8

How it went Today?

Craftingbugs - Nov 8

Announcing AppMap for GitHub - Runtime Code Reviews for Every Pull Request

Kevin Gilpin - Nov 9

How To Build AI Chatbots Using React JS in Minutes

Salmen Hichri - Nov 8

Once suspended, the_greatbonnie will not be able to comment or publish posts until their suspension is removed.

Once unsuspended, the_greatbonnie will be able to comment and publish posts again.

Once unpublished, all posts by the_greatbonnie will become hidden and only accessible to themselves.

If the_greatbonnie is not suspended, they can still re-publish their posts from their dashboard.

Once unpublished, this post will become invisible to the public and only accessible to Bonnie.

They can still re-publish the post if they are not suspended.

Thanks for keeping DEV Community safe. Here is what you can do to flag the_greatbonnie:

the_greatbonnie consistently posts content that violates DEV Community's code of conduct because it is harassing, offensive or spammy.

Unflagging the_greatbonnie will restore default visibility to their posts.

We're a place where coders share, stay up-to-date and grow their careers.

Writing Technical Articles

Read Strunk and White, Elements of Style . Again.

Give the paper to somebody else to read. If you can, find two people: one person familiar with the technical matter, another only generally familiar with the area.

Papers can be divided roughly into two categories, namely original research papers and survey papers. There are papers that combine the two elements, but most publication venues either only accept one or the other type or require the author to identify whether the paper should be evaluated as a research contribution or a survey paper. (Most research papers contain a "related work" section that can be considered a survey, but it is usually brief compared to the rest of the paper and only addresses a much narrower slice of the field.)

Research Papers

A good research paper has a clear statement of the problem the paper is addressing, the proposed solution(s), and results achieved. It describes clearly what has been done before on the problem, and what is new.

One goal of the paper is to ensure that the next person who designs a system like yours doesn't make the same mistakes and takes advantage of some of your best solutions. So make sure that the hard problems (and their solutions) are discussed and the non-obvious mistakes (and how to avoid them) are discussed. (Craig Partridge)

Paper Structure

The body should contain sufficient motivation, with at least one example scenario, preferably two, with illustrating figures, followed by a crisp generic problem statement model, i.e., functionality, particularly emphasizing "new" functionality. The paper may or may not include formalisms. General evaluations of your algorithm or architecture, e.g., material proving that the algorithm is O(log N), go here, not in the evaluation section.

Architecture of proposed system(s) to achieve this model should be more generic than your own peculiar implementation. Always include at least one figure.

Realization : contains actual implementation details when implementing architecture isn't totally straightforward. Mention briefly implementation language, platform, location, dependencies on other packages and minimum resource usage if pertinent.

Evaluation : How does it really work in practice? Provide real or simulated performance metrics, end-user studies, mention external technology adoptors, if any, etc.

• Related work, if not covered at the beginning.

The IEEE affirms that authorship credit must be reserved for individuals who have met each of the following conditions: 1) made a significant intellectual contribution to the theoretical development, system or experimental design, prototype development, and/or the analysis and interpretation of data associated with the work contained in the manuscript, 2) contributed to drafting the article or reviewing and/or revising it for intellectual content, and 3) approved the final version of the manuscript, including references.

Introduction

Here at the institute for computer research, me and my colleagues have created the SUPERGP system and have applied it to several toy problems. We had previously fumbled with earlier versions of SUPERGPSYSTEM for a while. This system allows the programmer to easily try lots of parameters, and problems, but incorporates a special constraint system for parameter settings and LISP S-expression parenthesis counting. The search space of GP is large and many things we are thinking about putting into the supergpsystem will make this space much more colorful.

Many new domains for genetic programming require evolved programs to be executed for longer amounts of time. For example, it is beneficial to give evolved programs direct access to low-level data arrays, as in some approaches to signal processing \cite{teller5}, and protein segment classification \cite{handley,koza6}. This type of system automatically performs more problem-specific engineering than a system that accesses highly preprocessed data. However, evolved programs may require more time to execute, since they are solving a harder task. Previous or obvious approach : (Note that you can also have a related work section that gives more details about previous work.)) One way to control the execution time of evolved programs is to impose an absolute time limit. However, this is too constraining if some test cases require more processing time than others. To use computation time efficiently, evolved programs must take extra time when it is necessary to perform well, but also spend less time whenever possible. Approach/solution/contribution : The first sentence of a paragraph like this should say what the contribution is. Also gloss the results. In this chapter, we introduce a method that gives evolved programs the incentive to strategically allocate computation time among fitness cases. Specifically, with an aggregate computation time ceiling imposed over a series of fitness cases, evolved programs dynamically choose when to stop processing each fitness case. We present experiments that show that programs evolved using this form of fitness take less time per test case on average, with minimal damage to domain performance. We also discuss the implications of such a time constraint, as well as its differences from other approaches to {\it multiobjective problems}. The dynamic use of resources other than computation time, e.g., memory or fuel, may also result from placing an aggregate limit over a series of fitness cases. Overview: The following section surveys related work in both optimizing the execution time of evolved programs and evolution over Turing-complete representations. Next we introduce the game Tetris as a test problem. This is followed by a description of the aggregate computation time ceiling, and its application to Tetris in particular. We then present experimental results, discuss other current efforts with Tetris, and end with conclusions and future work.

Body of Paper

Hints and common mistakes

Bibliography

• Avoid use of et al. in a bibliography unless list is very long (five or more authors). The author subsumed into et al. may be your advisor or the reviewer... Note punctuation of et al. .
• Internet drafts must be marked "work in progress". Make sure that they have been replaced by newer versions or RFCs. Any Internet Draft reference older than six months should automatically be suspicious since Internet Drafts expire after that time period.
• Book citations include publication years, but no ISBN number.
• For conference papers, you MUST name the conference location, month and the full conference name, not just some abbreviation. Page numbers are acceptable, but no longer all that helpful for electronic publications. All of this information is readily available via the IEEE or ACM digital libraries.
• Check if Internet drafts have been published as RFCs or if there's a newer version.

Jane Doe, "Some random paper", to be published, 2003.

is useless, as the paper has presumably been published by now. Google or the ACM or IEEE digital libraries will help you find it.

Acknowledgements

• Acknowledge your funding sources. Some sources have specific wording requirements and may prefer that the grant number is listed. The NSF requires text like "This work was supported by the National Science Foundation under grant EIA NN-NNNNN."
• Generally, anonymous reviewers don't get acknowledged, unless they really provided an exceptional level of feedback or insight. Rather than "We thank X for helping us with Y", you might vary this as "X helped with Y.".

Reporting Numerical Results and Simulations

In all but extended abstracts, numerical results and simulations should be reported in enough detail that the reader can duplicate the results. This should include all parameters used, indications of the number of samples that contributed to the analysis and any initial conditions, if relevant.

When presenting simulation results, provide insight into the statistical confidence. If at all possible, provide confidence intervals. If there's a "strange" behavior in the graph (e.g., a dip, peak or change in slope), this behavior either needs to be explained or reasons must be given why this is simply due to statistical aberration. In the latter case, gathering more samples is probably advised.

Figures should be chosen wisely. You can never lay out the whole parameter space, so provide insight into which parameters are significant over what range and which ones are less important. It's not very entertaining to present lots of flat or linear lines.

The figure and table captions should contain enough context so that a reader can understand the content of the figure or table without having to refer to the text. Any labels or uncommon abbreviations need to be explained in the figure or table caption.

The description of the graph should not just repeat the graphically obvious such as "the delay rises with the load", but explain, for example, how this increase relates to the load increase. Is it linear? Does it follow some well-known other system behaviors such as standard queueing systems?

LaTeX Considerations

• There's no need to enclose numbers in $$ (math mode).
• Use \cite{a,b,c} , not \cite{a} \cite{b} \cite{c} .
• Use the \usepackage{times} option for LaTeX2e - it comes out much nicer on printers with different resolutions. Plus, compared to cmr, it probably squeezes an extra 10% of text out of your conference allotment.

In the examples above, the index i or index is substituted or instantiated by numbers, such as x 1 , x 2 .

• Multi-letter variable names should be surrounded by \mathit , not $$, as otherwise the spacing will be wrong.
• For uniformity, use the LaTeX2e graphics set, not the earlier psfigure set: \usepackage{graphics} ... \begin{figure} \resizebox{!}{0.5\textheight}{\includegraphics{foo.eps}} \caption{Some figure} \label{fig:figure} \end{figure}

Things to Avoid

Guidelines for experimental papers.

"Guidelines for Experimental Papers" set forth for researchers submitting articles to the journal, Machine Learning .

• Papers that introduce a new learning "setting" or type of application should justify the relevance and importance of this setting, for example, based on its utility in applications, its appropriateness as a model of human or animal learning, or its importance in addressing fundamental questions in machine learning.
• Papers describing a new algorithm should be clear, precise, and written in a way that allows the reader to compare the algorithm to other algorithms. For example, most learning algorithms can be viewed as optimizing (at least approximately) some measure of performance. A good way to describe a new algorithm is to make this performance measure explicit. Another useful way of describing an algorithm is to define the space of hypotheses that it searches when optimizing the performance measure.
• Papers introducing a new algorithm should conduct experiments comparing it to state-of-the-art algorithms for the same or similar problems. Where possible, performance should also be compared against an absolute standard of ideal performance. Performance should also be compared against a naive standard (e.g., random guessing, guessing the most common class, etc.) as well. Unusual performance criteria should be carefully defined and justified.
• All experiments must include measures of uncertainty of the conclusions. These typically take the form of confidence intervals, statistical tests, or estimates of standard error. Proper experimental methodology should be employed. For example, if "test sets" are used to measure generalization performance, no information from the test set should be available to the learning process.
• Descriptions of the software and data sufficient to replicate the experiments must be included in the paper. Once the paper has appeared in Machine Learning, authors are strongly urged to make the data used in experiments available to other scientists wishing to replicate the experiments. An excellent way to achieve this is to deposit the data sets at the Irvine Repository of Machine Learning Databases. Another good option is to add your data sets to the DELVE benchmark collection at the University of Toronto. For proprietary data sets, authors are encouraged to develop synthetic data sets having the same statistical properties. These synthetic data sets can then be made freely available.
• Conclusions drawn from a series of experimental runs should be clearly stated. Graphical display of experimental data can be very effective. Supporting tables of exact numerical results from experiments should be provided in an appendix.
• Limitations of the algorithm should be described in detail. Interesting cases where an algorithm fails are important in clarifying the range of applicability of an algorithm.

Other Hints and Notes

From Bill Stewart (Slashdot, May 7, 2006), edited

Write like a newspaper reporter, not a grad student. Your objective is clear communication to the reader, not beauty or eruditeness or narration of your discoveries and reasoning process. Don't waste their time, or at least don't waste it up front. Hit the important conclusions in the first few sentences so your reader will read them. If you'd like to wrap up with them at the end of your memo, that's fine too, in case anybody's still reading by then, but conclusions come first. If you're trying to express something complex, simplify your writing so it doesn't get in the way. For something simple, 10th grade language structures will do, but if it's really hairy stuff, back down to 8th grade or so. Think about what your audience knows and doesn't know, and what they want and don't want. Express things in terms of what they know and want, not what you know.

From MarkusQ, Slashdot, May 7, 2006

Top down design Starting with an outline and working out the details is the normal way of tackling an engineering problem. Checking your facts Engineers should be used to checking anything that is even remotely doubtful before committing to it. So should writers. Failure mode analysis For each sentence ask yourself, could it be misread? How? What is the best way to fix it? Dependency analysis Are the ideas presented in an order that assures that each point can be understood on the basis of the readers assumed knowledge and the information provided by preceding points? Optimization Are there any unnecessary parts? Does the structure require the reader to remember too many details at once, before linking them? Structured testing If you read what you have written assuming only the knowledge that the reader can be expected to have, does each part work the way you intended? If you read it aloud, does it sound the way you intended?

The Conference Review Process

It is hard to generalize the review process for conferences, but most reputable conferences operate according to these basic rules:

• The paper is submitted to the technical program chair(s). All current conferences require electronic submission, in PDF, occasionally in Word.
• The technical program chair assigns the paper to one or more technical program committee members, hopefully experts in their field. The identity of this TPC member is kept secret.
• The TPC member usually provides a review, but may also be asked to find between one and three reviewers who are not members of the TPC. They may be colleagues of the reviewer at the same institution, his or her graduate students or somebody listed in the references. The graduate student reviews can be quite helpful, since these reviewers often provide more detailed criticism rather than blanket dismissal. Any good conference will strive to provide at least three reviews, however, since conferences operate under tight deadlines and not all reviewers deliver as promised, it is not uncommon that you receive only two reviews.
• In some conferences, there is an on-line discussion of papers among the reviewers for a particular paper. Usually, a lead TPC member drives the discussion and then recommends the paper for acceptance, rejection or discussion at the TPC meeting.
• The technical program chair then collects the reviews and sorts the papers according to their average review scores.
• The TPC (or, rather, the subset that can make the meeting), then meets in person or by phone conference. Usually, the bottom third and the top third are rejected and accepted, respectively, without (much) further discussion. The papers discussed are those in the middle of the range, or where a TPC member feels strongly that the paper ended up in the wrong bin, or where the review scores differ significantly. Papers that only received two reviews are also often discussed, maybe with a quick review by one of the TPC members as additional background. The rigor of the TPC meeting depends on the size and reputation of the conference. In some workshops and conferences, the TPC chairs may well make the final decision themselves, without involving the whole TPC.

Other References

• A series of short YouTube videos by Simone Silvestri: How to write an abstract , an introduction , a related work section ; how to comply with a double blind review policy
• Tips for Writing Technical Papers , January 2006
• Hewitt's 10 Commandments for Academic Writing
• George Orwell: "Vagueness and Sheer Incompetence is the Most Marked Characteristic of Modern English Prose"
• Grammar checker
• Links to grammar and usage guides
• Plain Language: Improving Communication from the Federal Government to the Public contains a number of helpful hints for writing clear prose.
• How to give a good research talk and how to give a good research talk
• How to read a paper , CCR, July 2007.
• How to Write a PhD Thesis
• Top 10 tips for writing a paper , by Jim Kurose
• 10 top writing tips and the psychology behind them ("write shorter", "shorten your sentences", "rewrite passive voice", "eliminate weasel words", "replace jargon with clarity", "cite numbers effectively", "use I, we and you", "move key insights up", "cite examples", "give use some signposts")
• Bartleby has dictionaries, grammars, an encyclopedia, and Columbia Guide To Standard American English
• Dictionaries and thesaurus: The Free Dictionary , Webster's (1913) , vocabulary.com , Fine Dictionary , Thesaurus - Synonyms, Antonyms, and Related Words
• Dictionarist : multi-lingual dictionary
• bab.la : an assortment of multilingual dictionaries
• IEEE IEEE Computer Society style guide, including hints on how to reference Internet drafts and RFCs
• USC editorial style guide
• Articles on technical communication
• Berkeley Information Systems and Technology Publications style guide
• Guide to Grammar and Style , by J. Lynch
• alt.usage.english FAQ, addressing common grammar questions
• Key to common comments made on your papers
• Religious Studies style sheet
• Oded Goldreich wrote an essay entitled "How not to write a paper" , with recommendations on style and organization.
• Terms to avoid for legal writing , applies in particular to amateur lawyers
• Don Knuth has online the TeX source of a book on "Mathematical Writing" (also useful for Computer Science).
• The structure of paper/report in Systems , by Michalis Faloutsos, U.C. Riverside

This is an amazing little book that you can read in a few hours. Your writing style will never be the same afterwards. This $8 book is the best investment you can ever make.

• "A Guide to Writing as an Engineer"
• Spring into Technical Writing for Engineers and Scientists
• Top ten writing tips for scientists, Sciencebase.com - basic overview of how to write about science

This is a great book that expands on Strunk&White. It has more examples, and was written by an author who edited numerous technical publications, many of which were in computer science.

This is the bible for American academic style. It's long and heavy, but has everything you ever want to know about style. When in doubt, or if you get conflicting stylistic advice, following The Chicago Manual of Style is your best choice.

This is another useful book written for publishing (computer) scientists.

• The UIST Guide for Authors is geared towards a specific conference, but the general process and guidelines are similar to many other conferences.
• The Science of Scientific Writing , George D. Gopen and Judith A. Swan, In American Scientist , Vol. 78, No. 6 (Nov-Dec, 1990), pp. 550-558.

This is a useful article that teaches scientists how to write single sentences and paragraphs, such as "follow a grammatical subject as soon as possible with its verb" and "articulate the action of every clause or sentence in its verb".

Mostly discusses non-technical writing, but many of the points apply.

It is an extensive resource explaining how to write papers, reports, memoranda and Ph.D. thesis, how to make high-performance slides and oral presentations, how to avoid common pitfalls and mistakes in English, etc., with many examples of "good" and "bad" practices.

• Roy Levin and David D. Redell, An evaluation of the ninth SOSP submissions -or- How (and how not) to write a good systems paper , ACM SIGOPS Operating Systems Review 17 (3):35-40 (July, 1983).
• Alan Snyder, How to get your paper accepted at OOPSLA , OOPSLA '91 Proceedings , pp. 359-363.
• Mark Allman, A Referee's Plea , 2001
• Ralph Johnson et al , How to get a paper accepted at OOPSLA , Panel at OOPSLA'93 , pp 429-436.

Generally useful advice that also applies to other networking conferences.

• How to write a great research paper
• What kinds of papers does USENIX publish?
• Alan Jay Smith, The Task of the Referee , IEEE Computer 23 (4):65-71 (April 1990).
• Grammar, Punctuation, and Capitalization , NASA SP-7084
• Stylewriter software
• Presenting a Technical Talk (Nick Feamster, 2013)
• Written Technical Communication (Klara Nahrstedt, 2010)
• Excellence in Oral Presentation for Technical Speakers (Klara Nahrstedt, 2010)
• "The Short Talk" (Charles Van Loan)
• "Pointers on giving a talk" (D. Messerschmitt)
• Tips for Preparing Delivering Scientific Talks and Using Visual Aids (ONR)

Miscellaneous

• Links to PhD resources
• International Standard Paper Sizes

Contributors

This page contains material provided by Gail Kaiser, Craig Partridge, Sumit Roy, Eric Siegel, Sal Stolfo, Luca Trevisan, Yechiam Yemini, Erez Zadok and João Craveiro.

Translations

German translation by Daniel Gruber

• Press Releases
• Privacy Policy
• Magazine Home
• CODE Focus Magazine
• My (Digital) Magazines
• Where is my Magazine?
• My Subscriber Account
• Consulting Home
• Services & Technologies
• Artificial Intelligence (AI)
• Cloud Computing
• Custom Application Development
• Executive Briefing (AI)
• Low-Code/No-Code
• Cyber Security
• Copilots in Your Apps!
• Project Rescue
• Business Document Copilot
• Legacy Conversion and Maintenance
• Free Hour of Consulting
• VFP Conversion
• Energy Software
• Staffing Home
• Our Services
• Training Home
• State of .NET
• CODE Presents
• Lunch with CODE
• Framework Home
• Get Started & Documentation
• Support & Services
• VFP Conversion Home
• Fox End of Life

Writing Technical Articles for CODE

Technical article objectives.

The objectives for CODE Magazine's technical articles ("How-To Articles") is to teach the reader how to use a certain technology, product, or technique. The author first sets the stage by introducing the scenario to make sure the reader understands what the article is all about and what the pre-conditions are. The author then methodically walks the reader through using the technology, technique, or product. The article focuses on how to do certain things. Articles do not focus on things that do not work. It may at times be beneficial to warn the reader of certain pitfalls and explain how to avoid them, but overall, CODE articles take a positive approach and focus on how to make things happen.

Article Format

Technical articles start with a brief intro paragraph. This is the paragraph people read and decide whether they want to read on. The introduction is also often used as an article abstract in eBooks and the like. Consider the intro to be an advertisement for the article. If the reader's interest can't be captured by the intro paragraph, the reader is not likely to read the entire article.

The article then progresses to methodically explore the topic at hand through explanations, code snippets (and listings), and screen shots (or other illustrative graphics). Make sure you explain topics thoroughly. CODE Magazine's philosophy is to take the space needed to explain technical aspects in detail. We want the reader to not just be aware of a certain technology or technique, but we also want the reader to be able to then apply whatever they learned without the need for further explanation or books or web sites.

Include Images and Screen Shots

Include screen shots and other images from your application. Screen shots should always be taken using standard color schemes (especially if you include screen shots showing source code, make sure you reset Visual Studio (or whatever IDE you are using) to the default colors. Send your screen shots as BMPs without compression. Never resize or compress images.

Photographs always need to be sent in high resolution (300dpi min). Photos of the development team or your offices are often interesting.

Note: In general, code examples should not be included as screen shots. Use code snippets or code listings instead (see below).

Code Snippets and Code Listings

Technical articles often require source code examples for illustration. Depending on the length of the example, we consider it either a "snippet" (10 lines or less) or a "listing" (more than 10 lines). Snippets are laid out in place within the flow of the article. Listings are positioned separately and referred to from the main text by listing number.

When creating code listings and snippets, copy the source code from your IDE using standard syntax coloring schemes. Make sure syntax coloring remains intact when pasting source code into articles. If you are using an IDE that doesn't create standard colored code you can paste, or have trouble with the coloring for another reason, check out our Code Snippet Tool , which can handle small snippets with appropriate coloring applied for most types of code. (However, it can't do everything, so if you have something beyond the capabilities of this tool, it is up to the author to provide appropriately colored content).

Make sure to use the latest CODE Magazine template and follow the code guidelines (especially number of characters per line) as defined in the template.

Length of Article

CODE Magazine articles do not have a specific length requirement or limit. It is our philosophy to take as much space for an article as is warranted by the topic to provide a good in-depth explanation to the reader, without wasting space or time. Typical CODE Magazine articles can be anywhere between 3 pages and a dozen pages. However, if your article topic is approved for writing, please coordinate with the editor to provide a rough estimate to enable us to plan space requirements.

Editorial Calendar 2023

We are currently planning the following lead-articles/topics:

• January/February: Smart Contracts/Blockchan
• March/April: Databases
• May/June: Mobile Development
• July/August: Web Development
• September/October: JavaScript and Node.js
• November/December: .NET Features

Please note that this calendar is tentative. CODE Magazine reserves the right to change topics at any time.

Questions? Contact Us!

If you are interested in writing for CODE Magazine, please email our Editor, Rod Paddock, or fill out the form here .

How to write the Perfect Technical Article

At Publitek, our team of writers spend the best part of their working day writing. The idea of facing a blank page every morning leaves some people cold, but it doesn’t have to. Writing, as it applies to the services provided to our clients, follows some fairly simple Golden Rules, which I’m going to share with you in this blog.

Writers write, right?

“Without rule 3 you could easily veer off course” Image credit: Mark Duffel

Before you can start to write the perfect technical article , you need to break the goal down into its three constituent parts; writing, perfection and a technical article. The good news is, you can already write. You may or may not think of yourself as a competent writer, but trust me, you are. Or at least you can be. Writing is something we all learn at an early age; it is a life-skill that has very clear rules. From this point of view, writing well becomes objective; if you follow the established and documented grammatical rules, your writing will be ‘correct’. There are even software tools and online platforms that can check your writing to make sure it complies with these grammatical rules. Once you get really proficient, you can break these rules with abandonment, rather than by accident, for extra emphasis. All the great writers do this. Some of the not-so-great writers get away with it. The key here is to remember there has to be a good reason for breaking the rules, and not knowing them isn’t a good reason.

Laying your trail of breadcrumbs

Writing well means communicating what’s inside your head to others in a way that makes sense to them, not just you. This raises the important topic of interpretation. In many forms of creative writing, reader interpretation is crucial, but for a technical article I would suggest that inviting reader interpretation should be used with caution. There will be times when you want the reader to arrive somewhere thanks to the trail of ‘breadcrumbs’ you’ve provided. But if that trail gets confusing, due to an unintentional (and metaphorical) fork in the road, then you risk losing the reader along the way. For technical articles, clarity is important. Understanding what you want to say is Golden Rule Number 1 and it is crucial that you have this defined before sitting down at that blank sheet of paper. If you do, that creative white space no longer seems quite so daunting. At Publitek, every piece of content we create starts life as a briefing form, which I like to describe as robust, but not rigid. We use these to define and agree the topics, key points and premises that we’ll be writing about.

You can’t please all of the engineers, all of the time

The next topic to address is the idea of ‘perfection’. Here, the sad news is, there is no such thing. What appears as perfect to some will be hogwash to others, and that’s the nature of humans. The most important point here is to always write with your audience in mind, and that’s advice that can be applied to any form of writing. The concept of a technical article is entirely subjective; it depends on the technical knowledge of the reader. You shouldn’t attempt to write anything that will appeal to everyone, because it will either be bereft of any real detail or be so tediously long that nobody would ever read it. Knowing your audience is Golden Rule Number 2 . This is particularly important when writing for publication in a trade magazine, because if you don’t write with the audience in mind the editor is unlikely to accept it for publication.

The last part of the equation is understanding what constitutes a technical article. You may work for a company with great technology, but you don’t need to tell the reader how good it is in every sentence. As I’ve already said, the term ‘technical’ will be subjective, but let’s assume that the article is aimed at an engineering audience. This immediately pares down the potential readership, but that’s ok, for the reasons outlined above. However, even within an engineering audience there will be different skill levels and specialities. The question now becomes, how much of that engineering audience am I trying to reach? This is where we begin to shape the flow of the article.

Like any piece of creative writing, a technical article should follow a story arc; it has a beginning, a middle and an end. The beginning will define the context for the middle and the end. If the context allows, the beginning will introduce the topic in a way that outlines the challenges and solutions covered in the rest of the text, in a way that will resonate most with the target audience.

This introduces the third Golden Rule; work within the context of your objective . This isn’t quite so simple as rules 1 and 2, but it is perhaps the most important. Without rule 3 you could easily veer off course and write an article that is little more than an advert. Failing to follow rule number 3 will also render rules 1 and 2 moot because you will have lost the audience before they have a chance to appreciate your proficiency in the first two.

Phil's Golden Rules to Great Technical Articles

Rule 1: Know what you want to say Rule 2: Know who you want to say it to Rule 3: Know your objective and stick to it Rule 4: Know your subject Rule 5: When it’s not quite right, you’ll know

Engineers like to be intrigued

We call it a story arc because we can think of it as a continuous, sweeping path from the beginning to the end, but as anyone who reads any kind of literature will appreciate, good stories always have a twist or two. This ‘sleight of hand’ is important, because it keeps the reader interested. Plot twists may not have a home in technical articles , but intrigue is important. Engineers are inquisitive, so will be looking for the ‘Aha!’ moment from the very first line. Delaying the big reveal can suspend this moment, but it shouldn’t be completely unexpected when it does arrive. Presenting a logical, reasoned argument is a key ingredient of a technical article, the more focused the article, the more detail required. The only way I know of doing this is to really understand the subject matter. Perhaps unsurprisingly then, knowing your subject is Golden Rule Number 4 .

Technical writing with style

It would be nice to round the number of golden rules up to 5, wouldn’t it? The rules described so far in are in no particular order, but they are all important. What remains is a long list of additional points that, effectively, come down to personal style. I don’t recommend imbuing technical articles with personality, as that isn’t the point (writers, please check your ego at the door). What is important is that the reader feels like the writer understands them. This isn’t just a repeat of Golden Rule Number 2, it goes further than that. It means being objective and not trying to hang the entire article off one point. It also means developing a style that eases the process of writing, conveys the authority and expertise of the writer, and leaves the reader feeling like the time they invested in reading your article was time well spent. This can really only happen with trial and error. To liken it to a contemporary megatrend, think of it as training an artificial intelligence; the more it fails, the better it gets. If I had to express that simply, as Golden Rule Number 5, I’d say practise, practise, practise .

At Publitek, we are trusted with generating millions of words of content every year, for a wide range of clients offering some sort of technology. Our writers have honed their skills over years of practice, they research the market, assess the solutions, evaluate the features and benefits and present the facts in a way that makes sense to engineers at every level. If that’s the sort of thing your company is looking for, drop me a line.

Philip Ling [email protected]

Share this post

About the author: publitek.

Related Posts

Building successful data-driven tech B2B marketing strategies

The changing face of engineering: 3 trends in the industry

Digital communications: next gen engineers versus career pros