Steve McConnell Logo

 Issue:  September/October 2002 | PDF

How to Write a Good Technical Article

IEEE Software  receives about 200 manuscripts each year, of which we publish approximately 50 to 75. Each manuscript goes through an in-depth peer review process and is reviewed by our associate editors in chief and me. In addition, guest editors review special-issue manuscripts.

Four years as editor in chief of  IEEE Software  have shown me countless examples of the differences between good and not-so-good technical articles. You might have wondered what you need to get a technical article published, either in  IEEE Software  or elsewhere. Here are some pointers.

One frequent misperception about  IEEE Software  is that it is a “journal.” In common parlance,  IEEE Software  probably is a journal in the sense that it publishes substantive papers of interest to leading practitioners. In IEEE parlance, however,  IEEE Software  is a magazine rather than a transaction or journal. The difference between these terms in IEEE-speak is that a magazine publishes articles and columns of contemporary interest to practitioners. Transactions focus more on publishing research results. There is no strong expectation that a transaction’s readers will read its papers as soon as they are published; rather, we expect readers to archive a transaction for future research purposes. We expect magazine readers to read a magazine’s contents close to when we publish them.

As a magazine,  IEEE Software  has more latitude than a transaction about the kinds of articles it publishes. We can publish reports of a single project or company’s experiences, and the findings need not rise to the level of statistically significant research if they provide valuable insights to our readers. Articles can also describe experiences with a new tool or practice, new ways of using old practices, new combinations of old practices, and so on. However, experience backed by data has a better chance of being published than purely anecdotal experience reports. Of course, we are also always looking for research findings that do rise to the statistically significant level, as long as those findings are of interest to leading software practitioners.

An important factor in my decision about whether to accept an article is how clearly the article is focused. A good article addresses exactly one topic. I have been surprised at how many submissions cover one-and-three-quarters topics poorly rather than cover one topic well. The solution is often simply to remove extraneous material. As Voltaire pointed out, an article is finished not when there is nothing more to add, but when there is nothing more that can be taken away. Similarly, a good article has a clear purpose. If I can’t determine the point the author is trying to make, I won’t accept the paper.

Our referees and readers have told us they dislike articles that evangelize a specific tool or methodology, especially if one specific company sells that tool or methodology. Candid experience reports are always welcome; dressed-up marketing pieces rarely make it past my desk into the review process. In contrast, our readers like articles about real, hands-on experiences. I give leeway to articles based on hands-on experiences, submitted by working practitioners who might not be well-versed in the nuances of writing for publication. As long as you clearly and honestly report the experience, you don’t need to worry about the writing being perfect.  IEEE Software ‘s excellent staff of editors can turn the report into a publication-quality article as long as the writing is technically accurate.

Writing Style

The best style for a technical article is to present background information and technical conclusions as clearly as possible. Other objectives are secondary to clarity.

I have received papers in which the author seems to be trying to impress readers with his or her intellect. Some papers use large words when synonymous shorter words would suffice, and others use sentences that are longer and more complicated than needed. Some papers create a profusion of needless acronyms or use mathematical formulas to present concepts that could be presented with one or two short sentences.

IEEE Software ‘s audience is software practitioners. Leading practitioners are busy people who place a premium on accessible information. Big words, complicated sentences, and formulas don’t impress them. Our readers value articles that quickly and blatantly cut to the heart of the issue at hand. The more practical the article, and the more it is directed toward practicing software developers and managers, the more likely we are to publish it.

The highest praise an  IEEE Software  article can receive is “It seems like common sense.” If an author can present a new concept so clearly that readers view it as common sense, the author has accomplished something significant.

Papers sometimes fall short in ways that can be easily avoided.

Lack of focus in multiauthor papers .  Many papers we publish have multiple coauthors. These papers frequently suffer from redundant sections written by different authors, from writing styles that differ grossly from one section to the next, and so on. Coauthor teams should appoint a lead author or editor who can make a final pass through the paper to check for redundancy and inconsistencies.

Overgeneralizing from experience .  While our readers love experience reports, I find that authors sometimes draw conclusions that extend beyond their reported experiences. For example, a paper that reports how much developer morale improved after using certain technical practices should not speculate that productivity will “probably” or “obviously” improve. Similarly, a paper can’t claim that a method improves portability, maintainability, or adaptability until the software concerned is ported, maintained, or adapted. A paper provides significant value by reporting even simple, narrow findings, but speculation beyond what the experience or data supports detracts from a paper’s contributions.

Too much academic background information .  Many papers spend pages providing background information on a familiar topic–for example, the Software Engineering Institute’s CMM for software. A college term paper might require such background, but a paper submitted for consumption by practitioners does better to provide a one-paragraph summary of familiar topic areas and direct readers to seminal books or articles on the topic. Readers are more interested in the author’s specific experiences than in reviewing familiar background material.

Reluctance to submit a short paper .  When reviewing submitted manuscripts, I sometimes get the impression that the authors had a good, clear idea but felt it was too small by itself to submit for publication. The authors then submit a paper with detailed background information, collateral material, and so on–which has the cumulative effect of obscuring the article’s real contribution. Our readers have been exceedingly clear that shorter is better. A paper should make its point and then stop.

Submitting a paper that is inappropriate for a theme .  Occasionally we receive a submission for a theme issue that is outside the theme’s scope. In the worst cases, the author has changed the paper’s title to match the theme, but the contents don’t match the title or relate to the theme. Submitting such papers is a waste of time for everyone involved. If you doubt whether your paper is appropriate for a theme, email the theme’s guest editors. They will help you focus your ideas in ways consistent with their theme, which maximizes the chances that we’ll ultimately accept your paper.

Expect to be edited .  It’s natural to become attached to writing into which you’ve poured precious evening and weekend hours. No one will be more familiar with a paper’s content than the author. However,  IEEE Software ‘s readers are accustomed to reading articles that are presented in a particular style. The job of  IEEE Software ‘s professional editing staff is to ensure that each article is ultimately published in a form that facilitates that connection between the author and our readers. Most authors don’t enjoy being edited, but if you keep an open mind, editing will almost always improve the quality of your paper. If nothing else, you’ll learn what someone else thinks is needed to connect with our magazine’s readers.

Authors should also address a few details that ease the reviewers’ and editors’ jobs. Submissions should contain

  • Page numbers on each page
  • An abstract or executive summary of 150 or fewer words
  • A list of keywords
  • Contact information for each author on the first page

In addition,  IEEE Software  does not generally publish articles that have been published elsewhere or that are simultaneously being considered for publication elsewhere.

My bottom-line question for an IEEE Software article is, “Does it make a contribution to the software engineering literature?” Some articles contribute by introducing a revolutionary concept or by synthesizing familiar concepts in a new way. Others contribute by providing an exceptionally accessible introduction to a specific topic or by providing an unusually clear and balanced survey of a topic area. A good article says something new or says something old in a new way. If you have ideas about an article you would like to publish, please do not hesitate to contact us at [email protected].

Editor: Steve McConnell, Construx Software   |   More articles

  • Skip to main content
  • Skip to search
  • Sign up for free

how to write technical article

Creating effective technical documentation

Author avatar

Effective feature documentation is important in enhancing a user's experience with the feature. Good documentation is like a piece of the puzzle that makes everything click — the key for encouraging feature adoption.

To support you in creating effective technical documentation, this article provides an overview of the core principles of technical writing. It also highlights the best practices for creating clear and accessible documentation. Applying these technical writing principles helps us maintain the high quality of content on MDN. Whether you're documenting your own project or product or contributing to technical content in various settings, you can improve the quality of your work by following these best practices.

Adopt clarity, conciseness, and consistency

These three Cs form the core principles of technical writing. They can take you a long way in producing quality documentation.

For achieving clarity in your writing, apply the following guidelines:

  • Use simple words and clear language. Keep in mind the audience, especially if it includes non-native English speakers.
  • Be clear about who needs to perform the action. Writing in active voice is not strictly required. However, you should use it when you want to be clear about who needs to perform the action. For example, clarify whether a function is triggered by an event or if the user needs to explicitly call the function.
  • Clearly introduce and explain new terms. This helps to lay the foundation for concepts that are covered later in the documentation.
Tip : Replace "it", "this", and "these" with proper nouns if they can refer to more than one thing in the given context.
  • Aim for one idea per sentence to improve readability.
  • Stick to one main idea per paragraph. Each sentence in a paragraph should logically connect to the one before it. Imagine if each sentence in a paragraph was a link in a chain. If you pick up the first link, the other links in the chain should follow, forming a continuous sequence. This is how the sentences should connect to each other, ensuring a seamless flow of a single idea.

Conciseness

Keep sentences short. This automatically increases the readability and clarity of your document. It also helps in quick comprehension. Long sentences can be more challenging to understand quickly due to their complex structures.

Tip : Based on common readability standards, aim for 15-20 words per sentence.

For additional insights on sentence length and readability strategies, see Simple sentences (on https://readabilityguidelines.co.uk ) and Popular readability formulas , including the Flesch-Kincaid index, on Wikipedia.

Consistency

Use the same terminology throughout your documentation to ensure a seamless reader experience. For example, if you start referring to "user agents" as browsers, stick with that term consistently. This avoids confusion that can arise from using words interchangeably, even when they share the same meaning.

Additionally, maintain consistent word casing and follow a uniform formatting style throughout your documentation. These practices not only enhance readability but also contribute to a professional presentation of your documentation.

Organize your content for maximum impact

Apply the same principles for organizing your content as you would for organizing your code: spend some time setting a clear goal and thinking about the desired structure for your documentation. Ensure that each subsection contributes to this goal incrementally.

Start with an introduction

In the introduction, first describe the feature you're documenting. Next, set the context by explaining why learning about the feature would be beneficial to the readers. This can include describing real-life scenarios where the feature can be useful. The more relevance you add to the topic, the easier it will be for readers to understand and engage with the content.

Progress logically

The following questions can help you ensure that your content is progressing logically:

  • Is your document structured to guide readers from foundational concepts to more advanced ones? Are there sections to introduce the " what " to establish a base before delving into the " why " and " how "? Consider whether the document structure mirrors the natural learning path for the topic. Aligning the document's structure with the natural progression of learning helps readers build their knowledge step-by-step and also enhances the overall learning experience.
  • Are there sufficient how-to guides or examples following the conceptual sections?
  • Consider the flow of the content. Is it following a logical sequence — from one sentence to the next, from one paragraph to the next, and from one section to the next? Does each section logically build on the information presented previously, avoiding abrupt jumps or gaps in the content?

Additionally, as you work on the draft, always ask yourself:

  • What reader questions am I addressing with this sentence?
  • Can I add a simplistic or real-life use case to explain this concept?

Include examples

Imagine sitting next to someone as you explain the concepts to them. Preempt their questions and address them in your writing. Use this approach to add as many relevant examples as possible.

When adding examples, don't restrict yourself to only code; include non-code scenarios to demonstrate a feature's utility. This helps readers understand the concepts better and also caters to different learning styles. Consider providing real-world scenarios or use cases to illustrate how the feature or concept applies in practical situations.

Optimize the document structure and length

Evaluate your documentation's structure to ensure it maintains a logical and balanced hierarchy.

  • Ensure that each section and subsection has a clear purpose and sufficient content.
  • Look for instances where a main section contains only one subsection (orphan), such as a single H3 section under an H2 section. This indicates that you need to reorganize your content or make some additions.
  • Check if there are lower-level headings such as H4 . Too many subsections can be overwhelming for readers, making it difficult for them to grasp the information. In such cases, consider presenting the content as a bulleted list instead to help readers retain the key points more effectively. This approach helps to simplify the hierarchy and also contributes to easier navigation.
  • While there should be sufficient content for each section, pay attention to the overall length. If any section becomes too extensive, it can be overwhelming for readers. Split large sections into multiple logical subsections or restructure the content into new sections and subsections. Grouping content into digestible pieces helps maintain focus and improve navigation for readers.

Proofread your writing

One aspect that cannot be stressed enough is the importance of self-reviewing and proofreading what you've written. Whether you're creating a large document or a short paragraph, this step is crucial.

Taking the time to fully review your work will help you identify sections that don't flow well or can be improved for clarity. During self-review, aim to spot and remove redundancy (repetition of ideas without adding value) and repetitiveness (overuse of words or phrases). These refinements will ensure your documentation is clear and coherent and conveys your ideas as intended.

Proofread and then take a break before you review again. Only then submit your work. While spell checkers can flag spelling errors, they might not flag incorrect use of words, such as an unintended use of "he" instead of "the". It's best to take a break and return with fresh eyes to catch any errors you might have missed. Pay close attention to identify inconsistencies in tone, style, tense, or formatting and make the necessary adjustments.

Additional tips

To improve the clarity and accessibility of your documentation, also keep the following guidelines and tips in mind. To go in-depth into any of the topics, feel free to consult our Writing style guide .

  • Bulleted vs numbered lists : Lists, in general, make documentation easier to scan. Use bulleted lists when there is no specific order of the items. Use numbered lists when the steps need to be followed in the specific order. Always include a lead-sentence before beginning a list to provide context.
  • Commas : Use a comma after an introductory clause to improve readability and to clarify the sentence structure. Use a comma to separate items in a list to ensure clarity.
  • Alt text : Always provide an alternative text for the images you add to content. This makes your documentation accessible to people using screen readers. In addition to images, ensure that video and audio files have accompanying descriptive texts.
  • Descriptive link text : Make sure each link text is clear even out of context and clearly indicates where the link leads. Descriptive link texts also help people using screen readers understand the destination of links. For example, use "Read our writing style guide to learn more" instead of "Click here to learn more".
  • Inclusive language : Make your documentation welcoming to everyone. Strive to use words that respect and acknowledge the diversity of your audience.

That's it for this article. I hope you found these tips helpful as a quick refresher on technical writing best practices. Remember that learning how to create effective and easy-to-use documentation is an ongoing process. It starts with understanding your audience and the goals of your documentation. By applying these technical writing principles and tips, you'll certainly be able to enhance the clarity and overall quality of your documentation.

Let me know if you learned something new or if there's any idea that resonated with you. I'd also like to hear if there are any best practices you use in your technical documentation workflow. Share with us on Mastodon or Discord .

Previous Post Leveraging Bun on Vultr: A superior Node.js alternative

Stay informed with mdn.

Get the MDN newsletter and never miss an update on the latest web development trends, tips, and best practices.

Lead image for How to Write Better Technical Content

How to Write Better Technical Content

Published on Jan 28, 2021 in writing by Karl Hughes 17 minute read

I recently spoke to the CTO Craft community about building a software engineering team blog . Towards the end, we got into some specific writing tips for software engineers who struggle to create strong technical content.

I’ve been writing online since at least 2010. I don’t remember if I published anything before that, but that’s the date of the oldest post I could find on my old Blogspot. In that time, my interests have changed a lot, but I’ve published relatively consistently along the way.

Most of my writing has been unpaid work done purely because the topic interested me, but in the past year since I started Draft.dev and turned writing into a career , I’ve started to think more critically about what makes good technical content.

In this post, I’ll share my tips for technology professionals looking to improve their technical content writing. Most of these tips will apply to anyone interested in writing, but they’ll be especially geared towards software developers as that’s my background.

This is a long post, so if you’d like to hop around, here’s what I’ll cover:

  • Don’t Expect to Be Very Good
  • Be Consistent Anyway
  • Writing is Organizing
  • Write as You Speak
  • Prove Your Point
  • Invest in Interesting Ideas
  • Tell People

Apply to write for Draft.dev

1. Don’t Expect to Be Very Good

“The skill and ability involved in writing sentences is generally underrated, and assumed to be a much more universal capacity than it really is…Most people know that they couldn’t write even a very bad song, or paint a picture, and understand their limits in that regard. On the other hand, everybody can write prose after some fashion, so it is not quite clear to them that they don’t actually have the ability to do it to a professional standard. That ability is quite a rare one.” - Philip Hensher, Professor of Creative Writing at the University of Exeter

By the time you graduate from high school, you’ve probably spent a fair amount of time writing. You might think you’re pretty good at it, but as soon as you dust off that old keyboard and start putting the proverbial pen to paper, you’ll quickly realize that writing is harder than it looks.

The problem here is what Ira Glass calls “ the gap :”

“All of us who do creative work … we get into it because we have good taste. But it’s like there’s a gap, that for the first couple years that you’re making stuff, what you’re making isn’t so good, OK? It’s not that great. It’s really not that great. It’s trying to be good, it has ambition to be good, but it’s not quite that good. But your taste — the thing that got you into the game — your taste is still killer, and your taste is good enough that you can tell that what you’re making is kind of a disappointment to you.” - Ira Glass

This gap is especially problematic for technical content writers like software engineers because the amount of information you have in your head is exponentially more than the amount you’ll be able to get onto a page in an hour . Software engineers who are new at writing get frustrated easily because they know what they want to say, but lack the language, typing speed, or organization skills to write about it well.

Your first 100 blogs, videos, posts, Tweets, lives, podcasts, creations will probably all be rubbish Get over that and get to it, get past that first 100 Hardly anyone will see it anyways, it’s practice for when they do That’s the price you pay for creating — The BKH - Show don’t tell ™🤝 (@thebkh) December 12, 2020

Just remember that everyone starts out as a beginner, and you can’t create skills overnight.

Find an Editor

Once you accept the fact that your early writing won’t be that good, it takes a weight off, but how do you actually start to get better?

A few years ago, I started dabbling in freelance writing . I remember thinking I was a pretty good writer, but my first draft back from an editor was riddled with suggestions . Some were simple formatting issues, but many were structural. I had to go back and rewrite large chunks of the piece to get it right.

If you aren’t ready to submit work to an editor yet, you can always enlist a friend for help. Even non-technical editors can help you improve your technical content writing . The best editors will be able to tell you when an idea you present doesn’t make sense or the piece is poorly organized.

2. Be Consistent Anyway

Many great projects go through a stage early on where they don’t seem very impressive, even to their creators. You have to push through this stage to reach the great work that lies beyond. But many people don’t. Most people don’t even reach the stage of making something they’re embarrassed by, let alone continue past it. They’re too frightened even to start. - Paul Graham

The key to getting better at writing is to do it consistently, even if you’re not that good at first.

Write Every Day

One way to write more is to write every day.

In 2017, I made a commitment to write every day. I didn’t hit that goal, but the year was still my most productive year as a writer to date. I wrote a book , updated many old posts on my personal blog, got paid to write a few pieces as a freelancer, and contributed to my company’s blog a few times. I don’t keep a word count (to me, that’s sort of like tracking how many lines of code you write), but I’m sure it was over 50,000 words.

“Measuring programming progress by lines of code is like measuring aircraft building progress by weight.” - Bill Gates

My friend Alex Lakatos is working on a similar effort right now :

💡On average, it takes 66 days to form a new habit. There's 65 left until 2021, so how about we start early on those New Year Resolutions? I'll start: I'm trying to publish content consistently, so I'll try to write a minimum of 100 words a day for the remainder of the year. pic.twitter.com/M0dHrJ36ef — Alex Lakatos 🥑🇬🇧 (@lakatos88) October 28, 2020

I don’t think you have to write every day forever to get better, but it will dramatically accelerate the speed at which you improve.

Block Time for Writing

“Because of technology, some people feel distracted – they can’t focus, that they can’t pay attention to what’s in front of them because their minds keep jumping around. They aren’t getting their work done; they’re not paying attention to their kids.” - Gretchen Ruben

A few months ago, I realized I wasn’t getting as many of the important things done as I would have liked. I started blocking my time off each week in 4-hour increments, focused on one thing I want to get done. Now my calendar looks like this each week:

Time-blocking my calendar

I want to devote 8-12 hours per week to writing consistently, so I literally block my entire Thursday and Sunday off for it. During blocks where I have meetings, I focus on sales and marketing tasks that are quicker and don’t require the same level of flow .

If you don’t do this, it’s way too easy to fall into the trap of endlessly checking email, scrolling through your Twitter feed, or playing Candy Crush instead of creating great content.

Deliberate Practice

“While regular practice might include mindless repetitions, deliberate practice requires focused attention and is conducted with the specific goal of improving performance…In the beginning, showing up and putting in your reps is the most important thing. But after a while we begin to carelessly overlook small errors and miss daily opportunities for improvement.” - James Clear

Once you make writing a habit, you have to figure out how to actively improve your craft. Creating great technical content requires focused practice with increasingly difficult tasks.

The mental model I like is called the zone of proximal development . The idea is that you will learn the most by maximizing your time doing tasks that are just outside your level of mastery.

Zone of proximal development

James Clear includes several examples in his essay on deliberate practice , but the most relevant to writing technical content is Benjamin Franklin’s story:

“When he was a teenager, Benjamin Franklin was criticized by his father for his poor writing abilities. Unlike most teenagers, young Ben took his father’s advice seriously and vowed to improve his writing skills. He began by finding a publication written by some of the best authors of his day. Then, Franklin went through each article line by line and wrote down the meaning of every sentence. Next, he rewrote each article in his own words and then compared his version to the original…Franklin realized his vocabulary held him back from better writing, and so he focused intensely on that area. Deliberate practice always follows the same pattern: break the overall process down into parts, identify your weaknesses, test new strategies for each section, and then integrate your learning into the overall process.”

The great thing for people wanting to be  technical content writers is that breaking down and rewriting existing tutorials is a fantastic way to both learn the technology and hone your craft as a writer.

Don’t Overcomplicate It

“Our life is frittered away by detail…Simplify, simplify.” - Henry David Thoreau

I really appreciate this diagram on writing by Doug Arcuri, but I think it overcomplicates the process for most new writers. While organization is important in writing (more on that in the next section), don’t let it overwhelm you.

The most important part is to start.

3. Writing is Organizing

The first two points above have been a little bit philosophical, but I want to spend the rest of this post getting tactical. I’m going to start with organization.

Most new writers don’t realize that organization is such an important part of writing. This is especially true in technical content writing where you’re trying to convey or teach a topic to a diverse audience. You want to give new readers the ability to build up to difficult topics while giving experienced readers the ability to skip to the parts they care about. The only way to serve such diverse readers is to invest time in organizing.

Start Every Piece With an Outline

Your 7th grade English teacher probably taught you to start with an outline, but by the time you got to 12th grade, you probably skipped that step to save time. Some writers think they know the topic well enough to skip outlining, but I can tell you it’s a really bad idea .

The outlining phase is where you prioritize ideas, identify weaknesses in your knowledge, and crystalize your main points.

I’ve also found that starting from an outline speeds up the writing process dramatically. With a well-thought-out outline, writing becomes the mere act of connecting the dots. Without one, it’s an unintelligible mess.

How Specific Should Your Outline Be?

My rule of thumb is to write an outline that covers all the H2 and H3 tags on the page.

Don’t stick to the outline like a rule-book; it’s more like a starting point. I often discover new ideas as I’m writing and need to move things around to accommodate them.

If you’re writing technical tutorials , you should create the demo application and outline the steps before you start writing the rest of the content. If you do it this way, you’ll find the writing part is very quick. It often takes me less than two hours to finish a 1500-word tutorial after I’ve written the code and outline.

Organization Methods

Organizing by color is one form of organizing by type

If you’re a new technical content writer, it’s probably hard to know how to start organizing technical content. There are four commonly accepted methods that I push people towards:

  • Chronological - Tutorials are typically organized from first step to last.
  • Importance - When presenting multiple options or comparing factors between tools, it’s usually a good idea to order them by importance.
  • Problem and Solution - I like framing posts around problems and solutions when they’re aimed at technical decision-makers.

Roundups (aka Listicles)

  • This method works well when you want to make information more scannable.

There are probably optimal organizational systems for different kinds of posts, but honestly, just having any system will make your writing better than most.

4. Write as You Speak

“Your writing should sound like you. Your vocabulary, your cadence, your syntax, your dialect. Your verbal idiosyncrasies. Friends and colleagues should be able to hear your voice in their heads as they read. Communication is a relationship, and to develop an authentic relationship with your reader, your writing – like your speech – should convey not only your opinion, but also a bit of your personality.” - Sarah Chauncey

I used to write technical documentation for Siemens medical imaging equipment, so I read and wrote a lot of dry documentation. That said, not all technical content needs to read like a user manual.

Blogs are great because they give you carte blanche to create your own voice. That said, adopting a specific voice for writing is really hard, so new writers should keep it simple and write like they speak.

Build Up to Each Concept

The other problem that subject matter experts encounter when they start writing is they forget most readers won’t be as knowledgeable as they are. Good technical writing and content is correct and uses industry-standard terms without overwhelming new readers. The trick is to build up to each concept as you deliver it.

The way I do this is by creating an outline that starts with no assumptions. For example, if I were writing an article about deploying Python workloads to Kubernetes, here’s what I’d start with:

  • What is Python?

What is Kubernetes?

  • What is a Kubernetes cluster?
  • What are the relationships between Kubernetes and containers?
  • Why deploy Python to Kubernetes?

How to deploy a Python web application to Kubernetes:

  • What is a workload in Kubernetes?
  • How do you prepare a Python application for Kubernetes?

While the focus of the article is on deploying a Python application to Kubernetes, I’d probably devote 2-3 paragraphs explaining the basic terminology. Then, I’d link readers to more comprehensive resources (like the documentation) to let them explore these topics in more detail.

This might seem like overkill, but an experienced reader will simply use the headers to skip down to the portion of the technical content they need. This extra context will only help people who are new to Python or Kubernetes ramp up to the meat of the article.

It’s admittedly hard to do this without shaving the yak , but you’ll get better at it the more you write and get feedback on your writing.

Yak shaving

Can You Be Too Casual?

Most writers tend to be too formal, but since I started editing more in the past year, I’ve realized that some fall towards the other extreme instead.

The important thing is to know your audience and the publication you’re writing for. If it’s your personal blog, you can be as casual as you want. If it’s for your company’s blog, you might want to make it a little more formal. The same goes for a technical writing blog.

My rule of thumb when writing technical content is to pretend you’re in a business meeting. If you wouldn’t say it in front of your boss, you shouldn’t write it in public.

Self-Editing

“Writing without revising is the literary equivalent of waltzing gaily out of the house in your underwear.” - Patricia Fuller

Editing is an entirely different skill than writing. I used to assume that anyone who could write could also edit, but I’ve since backed off that view. Writing is the big-picture process of organizing, researching, and molding ideas together. Editing is getting the nitty-gritty details right and asking if this whole thing even makes sense.

That said, good writers do at least a little bit of self-editing.

I do two things for every post I write before I hit publish:

  • Wait a few hours, then read it out loud - This helps me catch logical omissions and poor organization. Waiting a few hours helps me get a fresh perspective that I couldn’t get right away.
  • Run it through Grammarly - This helps me catch little details, misspellings, and wordy sentences.

Grammarly website

5. Prove Your Point

“The best way to show that a stick is crooked is not to argue about it or to spend time denouncing it, but to lay a straight stick alongside it.” - D.L. Moody

One of the few things I remember from my high school English class was my teacher’s insistence that every claim be backed up by a source. For some reason, that stuck in my future engineer’s brain, and it’s become a great asset now that I write for a living.

Good technical writing articles must be correct, so I pretend that my readers are all ornery skeptics hoping to poke holes in every statement I make.

There are three ways to add evidence to support your claims as a writer:

  • Research - Academic research typically has the highest bar, but business surveys or secondary research are sufficient for most informal technical content. Unfortunately, a lot of people don’t verify the research they use very carefully. This leads to a lot of technical content backed up by dubious claims taken out of context.
  • Quotes - I like quotes for a few reasons. They help break up long blocks of text by injecting an authoritative source, and they can add the weight of celebrity to your ideas. Again, be careful with verifying quotes.
  • Examples - People really like stories. While this can get naive readers into trouble, it’s helpful ammunition for writers. Personal experience or relevant anecdotes also help strengthen your claims.

6. Invest in Interesting Ideas

“Do not worry. You have always written before and you will write now. All you have to do is write one true sentence. Write the truest sentence that you know.” - Ernest Hemingway, A Moveable Feast

You probably have three or four ideas that you find interesting right now. For example, I’ve been thinking about the expert fallacy , what’s coming in the 2020s , and the idea that engineers are either farmers or pioneers .

I’ve written about these topics already, but something I never realized until this year was that as a writer, you can write about the same topic twice.

In fact, the best writers come back to the same few ideas repeatedly throughout their careers.

“The key is identifying all of the smaller components that go into the same topic and then fleshing each of them out until they are large enough to make up a complete piece of writing on their own.” - Louise Truscott

I can’t remember where I first heard this idea, but lately, I’ve been trying out ideas on Twitter . If they pick up a little traction, I’ll bring them into conversations and keep an eye out for other writing on the topic.

If it seems like others are interested in the idea, I’ll write a short bit about the topic in my email newsletter or on Reddit.

Finally, when I’ve run the idea through a few people and really honed it, I’ll compose a blog post on the topic. Here’s how this worked for my post on experts I mentioned above:

How an idea turns into a blog post

The idea started with a few tweets. People responded to them, and I refined the idea during a couple of conversations and a podcast I recorded for a friend. I read more from other writers on similar topics and eventually summarized my thoughts in my weekly email newsletter . Finally, I constructed the final product: a 2500-word blog post called The Danger in Listening to Experts .

Nobody is Truly Original

Written content doesn’t have to be completely original. A lot of writers get paralyzed when they can’t come up with a novel idea. Andy Haskell talked about his perfectionist tendencies in a blog post earlier this year:

“My perfectionist tendencies made it take forever to get a new post out the door, and caused me to feel like my content was going to be nothing new that people couldn’t already Google for. That narrative in my head left a lot of unfinished blog posts piling up.” - Andy Haskell

The truth is that all ideas are really mashups of existing ideas . That doesn’t mean your perspective on a topic won’t contribute to the world. You probably know many things that other software developers don’t know . When you create technical content online, you might just write it in a way that resonates with someone else. The opportunity to teach someone - even if the concept isn’t original - is enough to motivate most writers to power through at least a few blog posts.

Stay Open to Inspiration

“Most of what I “write” doesn’t even happen on the page. It happens while I’m away from the computer, when I’m in the line at the grocery store, waiting at the airport, or speaking with friends.” - David Perell

Ideas come from without, not within . That means you have to get out into the world if you want to come up with good ideas for technical content.

Software engineers do this by tinkering with new frameworks and languages. Product managers might try new organization tools. Designers might have conversations with artists for inspiration.

7. Tell People

“Distribution is the secret of the most successful blogs. Writing well is the cost of entry, but distribution takes you to the top.” - David Perell

I’ve been refreshing blog posts on my personal blog for the past couple of months. To illustrate the power of distribution, here’s the traffic on one of my old posts over the past year:

Traffic to an old blog post before I promoted it

I wasn’t actively promoting the post, but it was bringing in 60-120 pageviews per month thanks to Google searches. In November 2020, I decided to update the post and re-share it on social media. It got some upvotes on Hacker News and Reddit, and ended up bringing in 1204 pageviews that month alone.

After sharing, traffic to the post was 12x higher

Simply sharing this blog post led to a 12x increase in traffic to it over the course of a month. This is why writers should learn to share their content. If you want people to read your work, promoting it is essential.

If you’re looking for a checklist of ways you can promote technical writing blog posts, I put mine up on the internet earlier this year . Every piece of content is different, but this should give you a good starting point.

Final Thoughts

Writing great technical content won’t happen overnight. If you expect to be good at it from the start, you’re likely to be sorely mistaken, but stick with it. Writing is a great way to increase your influence and get noticed for your work.

Once you start writing, build a process for capturing and refining your ideas. Good technical content writing is almost always an amalgamation of existing concepts, but the more you compile these ideas, the better you’ll get.

Finally, tell the world when you write! Your knowledge is valuable, and it’s very rewarding to have people share and learn from your content.

Interested in writing for Draft.dev? Click here to learn more and apply today . Want access to our fantastic pool of writers? Schedule a call to learn more about what we do .

Karl Hughes

By Karl Hughes

Karl is a former startup CTO and the founder of Draft.dev. He writes about technical blogging and content management.

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.

  • 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

how to write technical article

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 2024

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

  • January/February: Web and Cloud Technologies
  • March/April: Artificial Intelligence / Machine Learning
  • May/June: Databases
  • July/August: JavaScript
  • September/October: Languagess
  • 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 technical article

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

Publitek | Innovative marketing for B2B tech companies Logo

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?

How to write a technical article

“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.

how to write technical article

Related Posts

How IIoT is transforming career opportunities in manufacturing

How IIoT is transforming career opportunities in manufacturing

Building successful data-driven tech B2B marketing strategies

Building successful data-driven tech B2B marketing strategies

The changing face of engineering: 3 trends in the industry

The changing face of engineering: 3 trends in the industry

DEV Community

DEV Community

Bonnie

Posted on Dec 3, 2021 • Updated on Feb 17, 2023

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)

pic

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

eichgi profile image

  • 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!

myogeshchavan97 profile image

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

davidchapuis profile image

Code Interview Prep: Longest Palindrome (Python)

David - Feb 14

janoskocs profile image

Deploy React App to EC2 using GitHub Actions—a love story

János K. - Feb 14

erinroseglass profile image

Level up your vulnerability management skills . . . painlessly

erin glass - Feb 14

alex_berdyshev profile image

Is a Career as a Blockchain Developer Worth It?

Alex Berdyshev - Feb 14

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.

DEV Community

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

  • PRO Courses Guides New Tech Help Pro Expert Videos About wikiHow Pro Upgrade Sign In
  • EXPLORE Tech Help Pro About Us Random Article Quizzes Request a New Article Community Dashboard This Or That Game Popular Categories Arts and Entertainment Artwork Books Movies Computers and Electronics Computers Phone Skills Technology Hacks Health Men's Health Mental Health Women's Health Relationships Dating Love Relationship Issues Hobbies and Crafts Crafts Drawing Games Education & Communication Communication Skills Personal Development Studying Personal Care and Style Fashion Hair Care Personal Hygiene Youth Personal Care School Stuff Dating All Categories Arts and Entertainment Finance and Business Home and Garden Relationship Quizzes Cars & Other Vehicles Food and Entertaining Personal Care and Style Sports and Fitness Computers and Electronics Health Pets and Animals Travel Education & Communication Hobbies and Crafts Philosophy and Religion Work World Family Life Holidays and Traditions Relationships Youth
  • Browse Articles
  • Learn Something New
  • Quizzes Hot
  • This Or That Game New
  • Train Your Brain
  • Explore More
  • Support wikiHow
  • About wikiHow
  • Log in / Sign up
  • Education and Communications

Technical Writing

Articles about technical writing.

how to write technical article

Write Dates

how to write technical article

Write an Appendix

how to write technical article

Write a Table of Contents

how to write technical article

Write a Canadian Date

how to write technical article

Write a Glossary

how to write technical article

Write Phonetically

how to write technical article

Write an Index

how to write technical article

Write a Technical Report

how to write technical article

Write a How to Guide

how to write technical article

Write Clear Instructions

how to write technical article

Write a Dictionary Definition

how to write technical article

Lead Into a Quote

how to write technical article

Create a User Manual

how to write technical article

Write a Tutorial

how to write technical article

Write a How To Article

how to write technical article

Write a Technical Specification

how to write technical article

Write Instructions

how to write technical article

Write a Soap Note

how to write technical article

Write a Manual

how to write technical article

Write a Caption

how to write technical article

Create a Control Chart

how to write technical article

Write a Test Plan

wikiHow

  • Terms of Use
  • Privacy Policy
  • Do Not Sell or Share My Info
  • Not Selling Info

Get all the best how-tos!

Sign up for wikiHow's weekly email newsletter

Technical Writing Tips And Tricks

The Benefits of Technical Writing: How to Write Better Technical Articles

Walle ai-writer , Story Ideas

Table of Contents

If you need help understanding a technical document, or want to know how to communicate complex information clearly and effectively, you’ve come to the right place. This guide to technical writing will help you make sense of difficult material and write clear, concise, and user-friendly documentation.

How To Use Technical Writing To Improve Your Business

There are a few ways that technical writing can help to improve business. Perhaps the most obvious way is that if a company produces technical articles or research papers, having a technical writer on staff can help to ensure that these documents are clear, concise, and accurate. This, in turn, can help to improve the company’s reputation and credibility.

Another way that technical writing can help businesses is by producing user documentation. This can be helpful for both customers and employees. Good user documentation can help customers to better understand and use a company’s products, and it can help employees to better understand and use the company’s internal systems. This, in turn, can lead to increased customer satisfaction and increased efficiency.

how to write technical article

Finally, technical writing can also help to improve business by providing computer science and electrical engineering students with real-world experience. By working with a company on technical projects, students can gain valuable experience that will help them in their future careers. This, in turn, can lead to the company getting access to talent that it might not otherwise have.

The Different Types Of Technical Writing

There are many different types of technical writing, each with its own specific purpose. The most common types are described below.

Instructional Manuals: These manuals provide step-by-step instructions for performing a task or using a product. They often include diagrams or other visuals to aid in understanding.

Operating Manuals: These manuals provide detailed information on how a system or machine works. They are typically used by engineers or other technical personnel.

Technical Specifications : These documents specify the requirements for a product or system like computer hardware. They are often used in tenders or other procurement processes.

User Guides: These guides provide information on how to use a product or system. They are typically written for non-technical users.

Technical Reports: These reports communicate the results of technical research or investigations. They are often used to communicate findings to clients or other stakeholders.

How To Use Technical Writing To Make Complex Topics Easier To Understand

Complex topics can be difficult for the average person to understand. This is where technical writing comes in. Technical writers are experts at breaking down complex topics and making them easy to understand.

One of the most common ways technical writers do this is by writing technical papers. Technical papers are designed to explain complex topics in a clear and concise manner. They often include diagrams and other visuals to help readers understand the concepts being discussed.

Another common way technical writers make complex topics easier to understand is by writing press releases. Press releases are brief, easy-to-read summaries of complex topics. They are often used to announce new products or services, or to provide an overview of a company’s latest research.

Consumer electronics are another common area where technical writers can be found. Technical writers often create user manuals and other documentation for consumer electronics products. This documentation is designed to help users understand how to use the product, and to troubleshoot any problems they may encounter.

There are many other technical and occupational fields where technical writers can be found. These include the medical field, the automotive industry, and the aerospace industry. In each of these fields, technical writers play an important role in helping to make complex topics easier to understand.

The Benefits Of Technical Writing

There are many benefits to technical writing, especially for those who wish to improve their writing skills or become more knowledgeable about a certain subject matter. Technical writing can be a great way to get more exposure to different topics and learn about new technologies, products, or processes.

Technical articles are often more concise and to-the-point than other types of writing, making them easier to read and understand. They also tend to be better researched and better sourced, which can add credibility to the author.

Native English speakers may find that technical writing is a good way to improve their English skills. The subject matter can be challenging, but the writing itself is usually clear and straightforward. Reading and writing technical articles can help improve grammar, vocabulary, and overall fluency.

Overall, technical writing can be a great way to learn more about a subject, improve writing skills, or simply gain more exposure to different topics.

Technical Writing Tips And Tricks

Technical writing is a specialized form of writing that is used to communicate complex information to a specific audience. Technical writers are often subject matter experts who use their knowledge of a particular field or technology to create documentation that is clear, concise, and easy to understand.

While there are many different tips and tricks that can be used to improve your technical writing, some of the most important are:

Use the active voice. The active voice is more concise and easier to understand than the passive voice, so it is important to use it whenever possible.

Keep your articles focused. When writing an article, make sure to focus on one specific topic or audience. Trying to cover too much ground will make your article difficult to follow and understand.

Use examples and tools. When possible, use examples and tools to help explain complex concepts. This will make it easier for your audience to understand what you are trying to say.

Get advice from experts. If you are having trouble communicating a complex concept, seek out advice from subject matter experts. They will be able to help you find the right words and phrases to use.

How To Become A Better Technical Writer

Technical communication is the process of conveying information from one person to another. It is an essential skill for any good writer. This article shows you how to become a better technical writer.

The first step is to understand the process of technical communication. This involves understanding the audience, the purpose of the communication, and the message that needs to be conveyed.

Once you understand the process, you need to focus on the content of your communication. This means ensuring that the information you provide is accurate and up-to-date. It also means choosing the right words to convey your message clearly.

The third step is to focus on the delivery of your communication. This means ensuring that your writing is well-organized and easy to read. It also means using the right tone and style for your audience.

The fourth and final step is to focus on the overall quality of your communication. This means proofreading your work carefully and ensuring that it meets the highest standards.

By following these four steps, you can become a better technical writer.

Technical writing is a field that is constantly evolving. As new technologies emerge, so do new opportunities for technical writers. While the future of technical writing is uncertain, one thing is certain: the demand for clear, concise, and accurate technical documentation will always be high.

We help writers get the stuff done BETTER , FASTER and CHEAPER…

Even IF you are just getting started or … you’re burnt out PRO

We’ve helped thousands of writers.

Now, at last, TTW is available again … and it’s just a ridiculously good deal, too…

What if you could….

  • Finally, get paid-well for your writing . You don’t have to compete for jobs against hundreds of people and in the end, earn pennies for your hard work.
  • Turn your passion for writing into a profitable and sustainable business. You’ll have the confidence, skills, and support you need to earn a serious income as a freelance writer .
  • No more hustling ten hours a day …and no more waiting for your articles to be approved – that go straight to the trash and never see the light of day again.

Here are two pricing plans:

For 30 days, then €10 per month, one-time payment, why is this little-known 2-year-old walle,, not backed by big vcs and created by a small team, still consistently humiliate well-known brands in head-to-head competition, by writing creative content that people & google love to read.

Do you think Ai writers can not write well without templates? Talk To Walle and you will discover the difference… and it’s been proving it for almost 2 years, using little-known  algorithm calibrated  by the team of underground devs that allowed it to zoom into the top ranks of the “underground: professional freelancers… and stay on top even as its not financed by Wall Street financiers. 

What’s more, by joining the TTW tribe you will learn the “underground” freelancers’ tactics that are held for the chosen ones.

How To  Kick-Start Your Awesome New Career  As a Respected, Sought-After,  Outrageously-Paid Freelance Copywriter?

Whether you’re already taking on freelance jobs (and need some help finding clients and increasing your fees)… or just beginning to dream about the lifestyle freedom and Big Bucks of a sizzling freelance career… this is your NEXT STEP in the process.

Listen: The business world is STARVED for writers who know how to write … and always will be.

Creating great copy and websites and ads that bring in results is the single most important element of a successful business…

… and yet, most biz owners haven’t got a clue how to pull it off.

That’s why a good freelance writer is so freaking valuable. In exchange for piles of cash, you will create the words that fuel all marketing, advertising, launches and profit-earning efforts.

Freelancers Are The Heroes of the biz world

And we are paid handsomely for the job. However… you got to know what you’re doing . And how to do it.

Now, you can shortcut your own path to becoming a respected, well-paid freelancer … by getting this AI writer.

Ridiculously popular AI text writer is finally available after months on waitlist

… Even If You Flunked High School English And Have Zero Professional Writing Experience ?

Perhaps you shouldn’t buy this…

… perhaps you should be tough and spend the next five years on creating-the-content the hard way

Because this model is : you gotta be tough if you gonna be stupid . 

So if you’re tough enough don’t buy this stuff.  

You’ll learn it yourself a thousand dollars and five years later .  

If you decide to buy you can access all of this immediately

Stop:   Before you do anything else with your career as a freelance writer, make sure  you check this out…

Why are writers using AI tools? And… What makes our AI writer so different ?

  • You don’t need templates  –  don’t kill your creativity – just think of an angle or a prompt and Walle will fulfill your writing needs 
  • Finally, you can use it on MOBILE
  • TTW is the ONLY tool that improves YOUR creativity and communication skills by well-thought prompt 

prompt – to make someone decide to say or do something – it’s a gateway to your imagination 

Imagination is more important than knowledge.   Knowledge is limited.   Imagination encircles the world. – Albert Einstein

You actually talk to the most powerful Artificial Intelligence Algorithm human created.

You learn how to effectively communicate  with others

  • Knowing how to listen well and communicate clearly will help you express yourself in job interviews , business meetings , and in your personal life as well.
  • Powered by state-of-the-art  OpenAI technology  to generate unique, original content for almost any vertical
  • Support for  major languages  to write in your own or other languages for your clients
  • Uses the newest  GPT-4 OpenAI algorithm  — to provide  best quality  output that requires minimal to no editing
  • No matter what kind of copy you need , the AI writer can produce it in a way that is easy for your readers to understand.
  • Whether you need more detailed information , a more edgy tone , or simply cleaner grammar , the AI writer can handle it.
  • If you’re unhappy with a sentence you’ve written, our AI text writer can help you  rephrase  it into something more elegant and concise.
  • The AI text writer will write the unique text that will pass a  Copyscape check

So, as one writer to another… I’m making this opportunity available to you.

No risk – take 30 days to decide..

Again, you may be exactly right for a wildly-successful freelance career. Or, you may not be a good “fit” at all.

Here’s your chance to find out both what the best in the biz know…

… and whether this is a career you want to follow.

No risk. Take a month to decide. But at least give yourself the best possible “behind the scenes” examination , so you KNOW.

Welcome to the most exciting adventure in business.

Testimonials

testimonial-stars

“I got more done last night than I have in the last month.”

“Walle has done the work for you.”

“AWESOME! Such a time saver.”

“Scaling my writing has never been that easy. Thank you, guys!”

Frequently Asked Question

FREE for 30 Days, then $10 per month, No Limits. Give it a try here .

Walle will help you generate articles, stories, product descriptions headlines and more. You can also check out some samples here .

Our AI writer writes word by word, which means it’s completely original. Our content passes all common plagiarism checkers, including Copyscape.

Walle creates text that you can publish instantly. For some companies with particular specifications, TTW’s main value is a brainstorming partner to help you get to your first draft.

You can easily pay online via Stripe, Apple Pay and major credit cards.

If you don’t like it for some reason, let us know within 30 days and we’ll be happy to refund you.

Email [email protected] , give us a detailed account of what happened, and we’ll work with you to make sure you have the best experience possible.

Related Posts

newspaper article outline

Newspaper Article Outline: How to Write an Effective Newspaper Article

AI WRITER Starting a freelance writing career

Starting a freelance writing career can be a great way to earn money and gain experience in your chosen field.

How to Reword an Essay to Improve Its Overall Effectiveness AI TEXT WRITER

How to Reword an Essay to Improve Its Overall Effectiveness

How to write a great technical blog post

Five steps to get from idea to polished result.

I’ve been working in the open source community for almost 5 years now, building and promoting developer tools including Meteor and Apollo . In that time, I’ve found that blogging is one of the most effective ways to spread ideas.

A blog post doesn’t take as long to prepare as a video or conference talk, but is easy to consume and can reach a ton of people. I’ve also personally gotten a ton of benefit out of writing: it has helped me organize my thoughts, teach people about technologies I love, and get my name out there.

Since publishing my first blog post ever in 2014, I’ve ended up writing 68 posts so far here on Medium, some with over 50k views and 1000 fans, and edited many posts for my friends and coworkers. Over that time, I’ve picked up a few strategies for taking a post from concept to publication.

In this article, we’ll go over five main steps of my process for writing a post:

  • Find a good topic and commit to it
  • Make your goals and audience specific
  • Have a beginning, middle, and end
  • Get feedback and iterate
  • Add finishing touches: packaging, publication, and promotion

Let’s get right into the first step!

1. Find a good topic and commit to it

You can’t get started on a post unless you have something to write about! When I talk to people who want to start blogging, this is often their main blocker.

The simplest strategy is to write about what you know. If you spent many hours learning about something, and you think you could explain it in just a few minutes, you’re going to provide a lot of value to your readers.

Another idea is to write about an area you think is lacking content. For example, right now there aren’t a lot of posts about how to apply to technical conferences, so content about that could fill a gap in the community.

Here are some specific types of posts you could go for. Examples are from the GraphQL-related posts on the Apollo blog:

  • A step-by-step guide to achieving a specific goal: “Building a great scrollable list in React Native with FlatList” or “Simplify your React components with Apollo and Recompose” . These are great for readers that are looking to get in, do a thing, and get out fast.
  • An in-depth survey on a particular topic: “Using nullability in GraphQL” or “Anatomy of a GraphQL query” . These are useful if you’re targeting a more interested audience that wants to grab a cup of coffee and learn a ton.
  • A numbered list of useful facts around a common topic: “4 simple ways to call a GraphQL API” or “5 benefits of static GraphQL queries” . These are a fun, lightweight read since you don’t have to commit to reading the whole thing, and it’s easy to consume the bite-sized pieces.

Now, let me dispel a few common concerns:

  • There is already content out there about this topic. Don’t let that stop you. Even if your idea has been written about before, you can put your own perspective on it, or make it specific to your situation.
  • My idea isn’t interesting enough. A lot of my friends and coworkers don’t end up writing because they are worried their conclusions might be boring or obvious. That’s a normal feeling! If you’re an expert on something, then of course the conclusions you’re writing about will be boring… to you . The key is that people in your audience don’t know that stuff yet.

Having said all that, at the end of the day, it’s hard to predict what topics will make a great post and which ones won’t, and often it’s the execution that makes or breaks a post, not a brilliant topic. My main suggestion would be to try writing about several different things and see what works.

49vpFzkVXA9fHTQoMGGDKEnqVDBIY4-eZ8d7

2. Make your goals and audience specific

Now that you know your topic, you need an audience and goal for your post. Who will be reading it, and what are they going to get out of it?

Your goal needs to be specific so that you can focus all of your energy on one main idea. For this post, the goal couldn’t have just been “write about blogging”. I needed a more specific goal in mind:

  • Audience: People who want to start blogging, especially about technical topics, but haven’t done it yet.
  • Goal: Give people a concrete set of steps and pointers so they can get started.

Once you have these, keep your post focused by removing anything that doesn’t contribute, and avoid adding extra detail just because it’s related. I’ve found that relatively concise posts with a 5 - 10 minute read time are the most successful.

Knowing the background of your audience will allow you to tailor your writing to their existing knowledge, and can help determine how you should publish and promote your content. For example, I hope to publish this on freeCodeCamp, because a lot of people in my target audience might already read that publication.

3. Have a beginning, middle, and end

It’s disorienting when a post veers off in a direction you weren’t expecting. Plot twists can be a big benefit in fictional short stories, but it’s easier to consume a technical article if you get exactly what you expect. You can keep your readers on track by giving your post a comfortable structure.

Introduction

The first paragraph or two of your post will either convince the reader to stay on or lose their attention. Start off with a little bit of context to help people understand where your post fits into the big picture. Then, tell your audience what they will get out of reading your article. It might be tempting to leave the big reveal for the end, but watch out: if you don’t have a good hook, your readers won’t stick around to find out.

Now that you’ve told your readers what to expect, give it to them! Feel free to go into as much detail as you need, and leave sign-posts along the way to orient people. Use a lot of headings, numbered lists, and formatting to help people understand where they are, and enable them to skip around to the content they are most interested in.

Don’t just taper off into the void at the end of the article. If your reader has made it all the way there, they really care. Give them a quick summary of what they learned, a pat on the back for reading, and maybe even something to do next if they’re inspired - a call to action.

The format I’m suggesting here isn’t the most creative, and there are certainly other ways of doing it. But a simple structure is the most direct way to communicate with your readers.

op8670wN9BlN6an-m9qZpZcFbitHwZnDFief

4. Get feedback and iterate

You won’t know what people are going to get from your writing until they read it. This is where your assumptions about your topic, goals, the details of the post, and the structure are really put to the test. If you want to have a good result, you can’t skip this step.

It might feel like you’re imposing when you ask for feedback, or you might be worried that it will be negative, but people are more willing to help than you expect. It’s much better to find out how your post could be better before you publish it to the world. When I was putting together this post, I got some super valuable feedback that made the content much better and more focused.

What should you ask your reviewers? My main advice is to leave it as open-ended as possible. Try not to explain up front what you meant to achieve. Hand over the draft as-is, and ask your reviewer what they got out of it or what should be changed. When someone on the Internet comes across your article, they won’t have any extra context and it has to stand on its own.

The main thing to validate from the feedback is: will this post achieve the goals you decided on in step 2? Iterate until you’re confident it will.

5. Add finishing touches: packaging, publication, and promotion

Now that you have the idea, the goal, the structure, and some feedback, it’s time to polish everything up and ship it.

Come up with a great title and subtitle, and make sure your post has at least one image. This is what people will see when the post is shared on Twitter or Facebook, and it’s your chance to get people interested in reading.

It’s also important that your post looks and feels professional, so that your content can really shine. You should aim to have no spelling errors, grammar mistakes, or weird formatting in your post. If you have a friend that is great at spotting small details, ask them to read it over before publishing.

The freeCodeCamp article about getting published also has some great tips about writing style and formatting. Since you’ve already put so much work into your post, it’s worth it to add that little extra effort to really polish it up and give it a wider reach.

Finally, make sure to credit anyone whose work you referenced, or who helped review and edit your post.

Publication

You’re almost there! Pick where you actually publish the post so that it has the best chance of reaching your audience. Medium is generally a great place for technical content, and makes it easy for people to discover your writing.

For bonus points, try to get your post into a relevant publication that will help share your content - in this case, I’ve selected freeCodeCamp because I think this advice will be relevant to their readers. If you’d like to do the same, here are their directions for submitting your post . Publications in your areas of interest are likely also looking for posts, so don’t be afraid to get in touch!

Once you’ve actually published the post, you’re not done! If you want people to see what you’ve written and get value out of it, make sure to share it in the places where your audience is likely to hang out. This might include Facebook groups, Reddit, Hacker News, LinkedIn, or any other platform. Also, make sure to share your creation on your own social media accounts, like Twitter. Your friends will be excited to read, share, and upvote what you’ve written!

And now, you’re done. Go get a coffee or take a walk - taking a blog post from start to finish is no small feat. Read any feedback and replies from the the community so that you can keep improving. And when you have another idea, go do it again!

lMYImUN-AHrgvCD74GhFaHyXGkIa6L0zP15z

There’s no replacement for practice

We just walked through five of the most important things to do when writing a blog post, from coming up with the idea to publishing. Now that you’ve read it, you try applying this advice and see what works for you.

I’ll leave you with one last bit of advice. The main thing I learned from blogging over the last 3 years is that I absolutely can’t predict what content will take off and what will end up being a total dud. Sometimes, I’ll put several days into a post, polishing every corner, and it won’t go anywhere. On the other hand, “GraphQL vs. REST” , my most-read post ever, was written in a few hours late at night.

So even if your first, or second, or third posts don’t succeed, keep trying new stuff, putting your ideas out there, and improving over time. The world wants to hear what you’ve got to say. Go tell them!

Huge thanks to Anvisha Pai , Angela Zhang , Katie Siegel , and the freeCodeCamp editors for helping review this post.

Read more posts .

If you read this far, thank the author to show them you care. Say Thanks

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

A band of clouds stretches from Hawaii to California and Oregon.

What is an atmospheric river? With flooding and mudslides in California, a hydrologist explains the good and bad of these storms and how they’re changing

how to write technical article

Hydrologist, Center for Western Weather and Water Extremes, University of California, San Diego

Disclosure statement

Qian Cao does not work for, consult, own shares in or receive funding from any company or organisation that would benefit from this article, and has disclosed no relevant affiliations beyond their academic appointment.

University of California, San Diego provides funding as a member of The Conversation US.

View all partners

Millions of Californians were under flood alerts as a powerful atmospheric river brought heavy rain to the West Coast in early February 2024. Los Angeles saw one of its wettest days on record with over 4 inches of rain on Feb. 4. Other communities were hit by more than 12 inches of rain and reported widespread flooding . Debris and mudslides shut down sections of highways and roads into Malibu .

It was the latest in a series of atmospheric rivers to bring extreme rainfall to the West Coast. While these storms are dreaded for the damage they can cause, they are also essential to the region’s water supply, particularly in California, as Qian Cao , a hydrologist at the University of California, San Diego, explains.

What are atmospheric rivers?

An atmospheric river is a narrow corridor or filament of concentrated water vapor transported in the atmosphere. It’s like a river in the sky that can be 1,000 miles long . On average, atmospheric rivers have about twice the regular flow of the Amazon River .

When atmospheric rivers run up against mountains or run into local atmospheric dynamics and are forced to ascend, the moisture they carry cools and condenses, so they can produce intense rainfall or snowfall.

Atmospheric rivers occur all over the world, most commonly in the mid-latitudes. They form when large-scale weather patterns align to create narrow channels, or filaments, of intense moisture transport. These start over warm water, typically tropical oceans, and are guided toward the coast by low-level jet streams ahead of cold fronts of extratropical cyclones.

Along the U.S. West Coast, the Pacific Ocean serves as the reservoir of moisture for the storm, and the mountain ranges act as barriers, which is why the western sides of the coastal ranges and Sierra Nevada see so much rain and snow.

Why are back-to-back atmospheric rivers a high flood risk?

Consecutive atmospheric rivers, known as AR families, can cause significant flooding .

The first heavy downpours saturate the ground. As consecutive storms arrive , their precipitation falls on soil that can’t absorb more water. That contributes to more runoff. Rivers and streams fill up. In the meantime, there may be snowmelt due to warm temperatures, further adding to the runoff and flood risk.

California experienced a historic run of nine consecutive atmospheric rivers in the span of three weeks in December 2022 and January 2023. The storms helped bring most reservoirs back to historical averages in 2023 after several drought years, but they also produced damaging floods and debris flows .

The cause of AR families is an active area of research. Compared with single atmospheric river events, AR families tend to be associated with lower atmospheric pressure heights across the North Pacific, higher pressure heights over the subtropics, a stronger and more zonally elongated jet stream and warmer tropical air temperatures.

Large-scale weather patterns and climate phenomena such as the Madden-Julian Oscillation , or MJO, also play an important role in the generation of AR families. An active MJO shift occurred during the early 2023 events, tilting the odds toward increased atmospheric river activity over California.

A truck drives through muddy streets that fill a large section of town. People stand on one small patch of pavement not flooded.

A recent study by scientists at Stanford and the University of Florida found that storms within AR families cause three to four times more economic damage when the storms arrive back to back than they would have caused by themselves.

How important are atmospheric rivers to the West Coast’s water supply?

I’m a research hydrologist, so I focus on hydrological impacts of atmospheric rivers. Although they can lead to flood hazards, atmospheric rivers are also essential to the Western water supply. Atmospheric rivers have been responsible for ending more than a third of the region’s major droughts, including the severe California drought of 2012-16.

Atmospheric rivers provide an average of 30% to 50% of the West Coast’s annual precipitation .

They also contribute to the snowpack, which provides a significant portion of California’s year-round water supply.

In an average year, one to two extreme atmospheric rivers with snow will be the dominant contributors to the snowpack in the Sierra Nevada. Together, atmospheric rivers will contribute about 30% to 40% of an average season’s total snow accumulation there.

A dam spillway with a full reservoir behind it.

That’s why my colleagues at the Center for Western Weather and Water Extremes at the Scripps Institution of Oceanography, part of the University of California, San Diego, work on improving atmospheric river forecasts and predictions . Water managers need to be able to regulate reservoirs and figure out how much water they can save for the dry season while still leaving room in the reservoirs to manage flood risk from future storms.

How is global warming affecting atmospheric rivers?

Warmer air can hold more moisture . As global temperatures rise in the future, we can expect more intense atmospheric rivers, leading to an increase in heavy and extreme precipitation events .

My research also shows that more atmospheric rivers are likely to occur concurrently during already wet conditions . So, the chance of extreme flooding also increases. Another study, by scientists from the University of Washington, suggests that there will be a seasonal shift to more atmospheric rivers earlier in the rainy season.

There will likely also be more year-to-year variability in the total annual precipitation, particularly in California, as a study by my colleagues at the Center for Western Weather and Water Extremes projects.

This article was update Feb. 5, 2024, with flooding and mudslides in California.

  • Climate change
  • Water security
  • Extreme weather
  • Extreme rainfall
  • Water supply
  • Atmospheric rivers

how to write technical article

Lecturer / Senior Lecturer - Business Law & Taxation

how to write technical article

Newsletters and Social Media Manager

how to write technical article

Research Fellow in Veterinary Herpesviruses

how to write technical article

Industrial Officer (Senior)

how to write technical article

Supply Chain Management – Open Rank (Tenure-Track)

IMAGES

  1. (PDF) PRINCIPLES OF WRITING A TECHNICAL PAPER

    how to write technical article

  2. 33 buenos ejemplos de redacción técnica (Word y PDF)

    how to write technical article

  3. 33 Good Technical Writing Examples (Word & PDF) ᐅ TemplateLab

    how to write technical article

  4. Technical Report Writing

    how to write technical article

  5. Writing Technical Articles

    how to write technical article

  6. Technical Report Writing

    how to write technical article

VIDEO

  1. IA SCHOLAR LECTURE SERIES#021: Easy Writing 6: How to Write a Strong "Conclusion" in Article

  2. A session on how to write technical paper by Dr. R.M. Kulkarni

  3. Article writing formate || How to write article in english. @AdityaSingh-xf8rv

  4. How To Write an Article in 7 Easy Steps #articlewriting

  5. How to write layout of review article with assisted tools in Hindi 2023

  6. How to Write Technical and High-Quality Articles with AI and ChatGPT

COMMENTS

  1. Technical Writing Process: How To Write A Good Technical Article

    In this article, you will learn about the technical writing process I use to write better technical articles for my clients. Here are the steps in the technical writing process that I will be covering: Step 1: Research. Step 2: Prepare to write. Step 3: Write the first draft. Step 4: Review. Step 5: Editing.

  2. Technical Writing for Beginners

    Technical writing is the art of providing detail-oriented instruction to help users understand a specific skill or product. And a technical writer is someone who writes these instructions, otherwise known as technical documentation or tutorials. This could include user manuals, online support articles, or internal docs for coders/API developers ...

  3. Developers: The Why and How to Writing Technical Articles

    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.

  4. Technical Writing Process: How To Write A Good Technical Article

    Write down a list of everything your target audience needs to learn in the technical article you will be writing. Step 2: Prepare To Write Firstly, determine the objective or aim for the article ...

  5. My 6-Step Process for Writing Technical Articles

    You need to do research, draft, edit and add graphics. In some cases, you will need to learn something completely new. Every writer will have some sort of process to help deal with this workload. My process started as a common checklist for every article. Breaking the article down step by step made the overall workload seem more manageable.

  6. How to Write a Good Technical Article

    Writing Style. The best style for a technical article is to present background information and technical conclusions as clearly as possible. Other objectives are secondary to clarity. I have received papers in which the author seems to be trying to impress readers with his or her intellect.

  7. Creating effective technical documentation

    Good documentation is like a piece of the puzzle that makes everything click — the key for encouraging feature adoption. To support you in creating effective technical documentation, this article provides an overview of the core principles of technical writing. It also highlights the best practices for creating clear and accessible documentation.

  8. How to Write Better Technical Content

    If you aren't ready to submit work to an editor yet, you can always enlist a friend for help. Even non-technical editors can help you improve your technical content writing. The best editors will be able to tell you when an idea you present doesn't make sense or the piece is poorly organized. 2. Be Consistent Anyway.

  9. 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.

  10. CODE Magazine

    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.

  11. Writing Systems and Networking Articles

    Writing Systems and Networking Articles. The notes below apply to technical papers in computer science and electrical engineering, with emphasis on papers in systems and networks. 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 ...

  12. How to write the Perfect Technical Article

    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 ...

  13. How to write a good Technical Article

    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 ...

  14. Technical Writing

    Articles about Technical Writing. Learn everything you want about Technical Writing with the wikiHow Technical Writing Category. Learn about topics such as How to Write Dates, How to Write an Appendix, How to Write a Table of Contents, and more with our helpful step-by-step instructions with photos and videos.

  15. How to Choose a Topic for Your Technical Article

    In it, I will give you tips that will save you the headache the next time you need to pick a topic for an article. Here's an overview of what this article will cover: Brainstorming. Decide why you want to write. Follow your interests. Everything has already been written about. Don't rehash the docs.

  16. PDF HOW TO WRITE A GOOD TECHNICAL ARTICLE

    I HAVE FIVE CARDINAL RULES FOR WRITING TECHNICAL ARTICLES: 1. Tell a story. Keep the organization of your article linear and focused. 2. Be clear, be concise. Try to engage your readers, not bore them with well-known information or arcane minutiae. Don't sacrifice clarity in an attempt to shorten your writing, however. 3.

  17. Tips for writing a good Technical Article

    Conversely, when the article is written in the present tense, the language is clear and unambiguous. #2: Avoid lengthy, complex paragraphs. In case your article will appear in columns, even one or two sentences equal a paragraph. #3: Avoid use of passive voice. For example " Each message includes a time interval " (active voice) reads ...

  18. (PDF) How to Write a Good Technical Article

    March 1983 · Proceedings of the IEEE. In A Guide for Writing Better Technical Papers, Craig Harkins and Daniel Plung show admirable concern with all aspects of the writing process through their ...

  19. How To Write an Appealing Technical Article

    But, yes, you may also need to add some inline code like this one. To do so, you can write ALT 96 (on European keyboards. It reproduces the backtick " `" in the American one) and the inline ...

  20. The Benefits of Technical Writing: How to Write Better Technical Articles

    Perhaps the most obvious way is that if a company produces technical articles or research papers, having a technical writer on staff can help to ensure that these documents are clear, concise, and accurate. This, in turn, can help to improve the company's reputation and credibility. Another way that technical writing can help businesses is by ...

  21. How to Write a Technical Article and Be Read

    The practical case. This part is the core of the article. The introduction is the way to convince the reader to start the article and the explanation is needed to give the right background to the ...

  22. 7 Tips for Effective Technical Articles

    Technical Writing is a crucial skill and there are many people who possess good technical skills but are not able to write a technical article in a very effe...

  23. Technical Writing Articles

    Here is the collection of technical writing article links. This article from U.S. News provides a thorough overview of the technical writing field. An in-depth article on how to write for the web and what online readers look for. An article providing information about how to write a white paper. An article providing a look into the ethic side ...

  24. Labeling AI-Generated Images on Facebook, Instagram and Threads

    That's why we've been working with industry partners to align on common technical standards that signal when a piece of content has been created using AI. Being able to detect these signals will make it possible for us to label AI-generated images that users post to Facebook, Instagram and Threads. We're building this capability now, and ...

  25. How to write a great technical blog post

    Make your goals and audience specific. Have a beginning, middle, and end. Get feedback and iterate. Add finishing touches: packaging, publication, and promotion. Let's get right into the first step! 1. Find a good topic and commit to it. You can't get started on a post unless you have something to write about!

  26. What is an atmospheric river? With flooding and mudslides in California

    Want to write? Write an article and join a growing community of more than 178,300 academics and researchers from 4,876 institutions. Register now. Editorial Policies; Community standards;

  27. How to use a contour layer or other data types for Elevation ...

    If you have elevation data in other formats, like contour layers or spot elevation data, then you must convert it to raster before using the tool. InfoWater Pro's Elevation Extractor uses a raster layer, a continuous surface DEM (Digital Elevation Model), to write elevation data to node elements in your model and calculate 3D pipe lengths.