writing a technical report

Want to create or adapt books like this? Learn more about how Pressbooks supports open publishing practices.

Chapter 1: Introduction to Technical and Report Writing

Bay College

Learning Objectives

What is Technical Writing? [1]

You’re probably wondering what this “technical writing thing” is. Someone may even have told you, “It’s this course where they make you write about rocket science and brain surgery.” Well, not really, as you will see in a moment. Actually, the field of technical communication is essential in a wide range of fields and occupations. It is a fully professional field with degree programs, certifications, and—yes!—even theory. It’s a good field with a lot of growth and income potential; and an introductory technical-writing course for which this book has been developed is a good way to start if you are interested in a career in this field .

Technical writing is an audience-centered means of communication that provides a reader with clear and easy access to information. In the business world, time equates to profit, and profit is the force behind all business interaction. The technical writer and reader have a vis-à-vis relationship. The writer recognizes, respects, and addresses the importance of time in effective and efficient communication by providing documents written in specific formats, using unambiguous language to send clearly accessible information. The reader in turn thoroughly understands the information in order to give a thoughtful response.

The Meaning of “Technical”

Technical communication—or technical writing, as the course is often called—is not writing about a specific technical topic such as computers, but about any technical topic. The term “technical” refers to knowledge that is not widespread, that is more the territory of experts and specialists. Whatever your major is, you are developing an expertise—you are becoming a specialist in a particular technical area. And whenever you try to write or say anything about your field, you are engaged in technical communication .

Academic Writing Versus Technical Writing    

The definite purpose, strict format and use of appropriate language in technical writing define the differences between technical writing and academic writing.  The academic writer’s purpose may be to write an assignment, a story, a letter, etc.. These works may or may not have a reader. However, technical writing always has a definite purpose and will always have a reader.  Regardless of the number of the intended readers of a document who may or may not read the document, the document will be read by the primary reader.

Workplace Writing

However, the focus for technical-writing courses is not necessarily a career as a technical writer but an introduction to the kinds of writing skills you need in practically any technically oriented professional job. No matter what sort of professional work you do, you’re likely to do lots of writing—and much of it technical in nature. The more you know about some basic technical-writing skills, which are covered in this guide and in technical-writing courses, the better job of writing you’re likely to do. And that will be good for the projects you work on, for the organizations you work in, and—most of all—good for you and your career .

Really Technical Writing

Keep relaxing, but you should know that professional technical writers do in fact write about very technical stuff—information that they cannot begin to master unless they go back for a Ph.D. But wait a minute! The technical documents have to ship with the product in less than nine months! How do they manage? Professional technical writers rely on these strategies to ensure the technical accuracy of their work:

• Study of books, articles, reports, websites related to the product
• Product specifications: what the product is supposed to do, how it is designed
• Interviews with subject matter experts: the product specialists, developers, engineers
• Product meetings during the development cycle
• Live demonstrations of the product
• Familiarization with similar, competing products
• Experimenting with working models of the product
• Most importantly, subject matter experts’ review of technical writers’ work for technical accuracy and completeness

Of course, experienced technical writers will tell you that product development moves so fast that specifications are not always possible and that working models of the product are rarely available. That’s why the subject matter experts’ review is often the most important.

Considerations of Technical Documents

There are key components of what makes a document strong. Therefore, writers keep these items in mind while constructing technical documents.

The Importance of Audience

Another key part of the definition of technical communication is the receiver of the information—the audience. Technical communication is the delivery of technical information to readers (or listeners or viewers) in a manner that is adapted to their needs, level of understanding, and background. In fact, this audience element is so important that it is one of the cornerstones of this course: you are challenged to write about highly technical subjects but in a way that a beginner—a nonspecialist—could understand. This ability to “translate” technical information to non-specialists is a key skill to any technical communicator. In a world of rapid technological development, people are constantly falling behind and becoming technological illiterates. Technology companies are constantly struggling to find effective ways to help customers or potential customers understand the advantages or the operation of their new products .

Not only is the the level at which you write important but so are the language choices you make as you do so. Please review the information on the following link for tips: Use Language that is Sensitive to Your Audience [2]

So relax! You don’t have to write about computers or rocket science—write about the area of technical specialization you know or are learning about. Also, plan to write about it in such a way that even Grandad can understand !

Formatting and Language

Formatting and appropriate language are the basic design elements of all technical documents.  A format that shows a hierarchical structure and a coordinate structure of information  le ads the reader thorough text.

Readers should be able to identify a writer’s organizational pattern very quickly when reading a technical document . This sometimes refers to a document being “reader friendly.”  In addition , using appropriate language is significant in providing the reader with a thorough understanding of the purpose of the document, how the document relates to the reader’s needs, and what action is expected of the reader. [3]

A document may also have one reader (the primary reader) or several readers (the secondary readers). A primary reader is the person who ordered the report to be written or the person for whom a report is intended. These readers will usually read the entire report. Secondary readers are those readers who will read only the sections of the report that relate to them, their jobs, their departments, responsibilities, etc. For example, if a report was sent that detailed funding for different departments, a piping superintendent may only want to read the section that relates to piping. This is where format, the use of headings, is significant in allowing the reader easy access to information. When the piping superintendent can scan through the document and clearly find the heading that identifies his department saves time.

Cultural Communication

Technical writers need to be aware of the differences between the behavior and the norms, beliefs and values of specific cultural. According to Edward T. Hall and Mildred Reed Hall, In Understanding Cultural Differences, each culture operates according to its own rules (1990, pp. 3-4).  Hall and Hall add that problems occur when members of one culture apply the rules to another culture (1990, pp. 3-4). To communicate effectively with other cultures, the technical writer needs to not only be aware of rules governing behaviors that can be observed but also of the not-so-obvious rules that govern the norms, beliefs, and values of the people of a culture. The invisible rules of a culture dramatically impact the acceptance of ideas, plans, and strategies.  The Cultural Iceberg illustrates patterns of world communication, showing indicators of Institutional Culture (the obvious behavior of a culture), which can be clearly seen as the tip of the iceberg, and People Culture (the norms, beliefs and values of a culture), which cannot be seen and which are the barriers to successful communication .

Figure 2 The Cultural Iceberg

Technical writers have a responsibility to their readers and to their employers to follow ethics when writing reports. 

Technical writers must use words that demonstrate valid appeals to reason, avoiding emotional words and phrases that appea l to basic emotion instead of justifiable reasoning. In addition, technical writers must use valid references to support ideas and strategies, avoiding referencing non experts to sway readers’ support. Also, technical writers must use accurate numbers to report data, avoiding charts and tables that skew data. Using any type of fallacies in technical writing is unethical and could result in dire consequences.

Not only do technical writers have a responsibility to report accurate information, but they also have a responsibility to credit accurate sources of information. At no time is it acceptable to rearrange information in order to attempt to indicate that the writer is the source of someone else’s idea or to indicate that the writer read a report that included information he/she cited, when the primary source of the information was cited in another report.  All sources must be referenced accurately in the text and cited on a reference page.

Daniel G. Riordan (2005), in Technical Report Writing Today, cites Dombrowski to define three threads of ethics:

One major thread is that the communicator must be a good person who cares for the audience. Communicators must tell the truth as convincingly as possible, because truth will lead to the good of the audience. Another thread is that the communicator must do what is right, regardless of possible outcomes. A third thread is that communicators must act for the greatest good for the greatest number of people (p. 16) .

In addition, Riordan (2005) references the “code of ethics of the Society for Technical Writers, and cites five of the code’s tenants:

My commitment to professional excellence and ethical behaviors means that I will …

• Use language and visuals with precision.
• Prefer simple direct expression of ideas.
• Satisfy the audience’s need for information, not my own need for self-expression.
• Hold myself responsible for how well my audience understands my message.
• Report the work of colleagues, knowing that a communication problem may have more than one solution (Riordan, 2005, pp. 15-16) .

Hall, E. T. & Hall, M. R. (1990). Understanding Cultural Differences. Yardmouth: Intercultural Press, Inc.

Riordan, D. G. (2005).  Technical Report Writing Today.  Boston: Houghton Mifflin Company.

Visuals & Readability

To make a document more reader friendly, many technical writers rely on visuals to achieve this goal. [5] For example , la bels, callouts and captions are identifying text for graphics . Labels and callouts identify specific elements or features on a graphic; whereas captions are short phrases or sentences that describe the graphic. Notes, or footnotes, explain, or give credit.

Labels and Callouts

To identify specific elements or features, labels and captions are placed directly on the graphic or near it. “Although the terms are used interchangeably, labels are text identifiers that are self-explanatory in an image, while callouts are labels that require further information outside the image to explain what they are identifying” (Gurak 304). They supplement the visual information. But use them selectively; use them only if readers need them (Rude 116).

The advantage of labels is that the reader gains a basic understanding of elements in the graphic without referring to supplementary explanations. But, too many labels obscure the image. In this case, callouts are the better option. Use numbers or letters to identify each element and the supplementary explanations.

Guidelines for Creating Labels and Callouts

• Determine the number of items to identify in the image (Gurak 308).
• Estimate how much explanation each item requires to determine if labels or callouts are more appropriate (Gurak 308).
• create a consistent visual style (Gurak 308)
• use the same terms on the label or callout as in the text (Rude 116)
• in general, all parts mentioned in the text should have a label or callout, and all parts with a label or callout should be mentioned in the text. (Rude 116)
• Use a standard font and size for readability (Rude 116)
• Align the labels and callouts for a neater appearance (Rude 116)
• If callouts are used, place the explanatory text in a key next to the graphic.

Labels can take different forms (Gurak 304 – 306):

• They may be placed directly on the graphic (whereby they become part of the graphic).
• They may be placed around the graphic and use lines to point to the relevant element in the graphic.
• Online, labels can be links or hotspots whereby more information about the element is displayed on mouse rollover.

This is an example of l abels placed directly on the graphic.

Figure 3 Map of the West Side Central Park, NYC between 102nd and 110th Streets.

Here, the labels are placed around the graphic.

Figure 4 Parts of a flower.

In this sample, when the mouse is rolled over the ‘Firebox’ label, the text will read: “Literally a box containing the fire. It is surrounded by water on the top and all sides. The bottom is a grate with an ash pan below that.” Additional information is displayed .

Figure 5 Labels as hotspots.

Callouts are best used when many parts of the image need to be labeled and each part requires a longer explanation. In fact, the label sequence may be in alphabetical or numerical (as in Figure 6) order. Ensure that the explanation is near the graphic.

Figure 6. How to understand and use the Nutrition Facts Label.

Coded callouts are in numerical sequence; the explanation for each number appears below the graphic. The example above shows part of the explanation of Number 1 explanation only.

Captions, table, and graphics titles must clearly identify information to the reader. Interpretive captions usually require one or more sentences. Captions should be informational, without becoming too lengthy. Captions that are merely a title for a graphic are not very helpful (Franklin 96).

Writing Style for Captions

• Captions for graphics include the title and any explanatory material, immediately under the graphic.
• Words such as Figure, Illustration, and Table should be in bold type.
• The caption should be italicized.
• Treat tables and figures the same.

Good captions are what guide readers not only to see, but also to understand. Captions label graphics with titles and explain to readers what they are seeing, and how to interpret the information captured in the visual. The Franklin Covey Style Guide for Business and Technical Communication provides an excellent source for writing captions (Franklin 39 – 41).

Five Specific Style Rules

• Use interpretive captions whenever possible. I nterpretive captions provide both a title and explanatory information, usually expressed in a complete sentence, to help readers understand the central point(s) that the writer wants to convey. A graphic and its caption should be clear and understandable without requiring readers to search for clarifying information in the text:
• Figure 4. Cabin-Temperature Control System. Constant cabin temperature control is maintained by the system’s modulated cabin sensor.
• This interpretive caption gives the title and then tells the reader the principle message – that the check valve provides near-zero risk. And, it states how the check valve provides near-zero risk (Franklin 39).
• Figure 23. Check Valve . The risk of bad air entering the changer is near zero because the check valve permits air flow in one direction only.
• This interpretive caption gives the title of the figure and emphasizes that the cabin has a constant temperature – a benefit provided by the feature described in the figure. The caption states clearly what the writer wants the reader to learn from the drawing (Franklin 39).
• Avoid using short, often ambiguous, titles to replace interpretive captions. In the past, styles for technical and scientific documents used only short, simple title captions for visuals. These were often superfluous, providing no real information other than the obvious to the reader, i.e. – A Horse. Titles that are so short and cryptic that they sound telegraphic are not useful. Such captions are only useful when the graphics are self-explanatory, and require no interpretation (Franklin 40).
• Number figures and tables sequentially throughout the document, and place the number before the caption. If an important figure or table is presented twice, treat it as two separate visuals and number each. Figure and table numbers should be whole numbers (Franklin 40).
• Captions may appear below or above a visual, but consistency throughout a document is critical. Arguments support both options; choose one, warrant your choice, and be consistent.
• Put the caption above the visual for better visibility when captions are used with slides and other project visual aids. Captions placed at the bottom may be blocked by the heads of those seated in front (Franklin 99).

Notes or footnotes are categorized as either explanatory or source notes. Explanatory footnotes are identified by a superscript number or letter. The order in which notes appear is important; explanatory footnotes are placed above source notes. And both are placed above the caption, if the caption is placed at the bottom of the illustration.

Figure 7. Placement of footnote, source note and caption.

Source: Rude, p. 115, modified.

The Writing Process [6]

Writing, especially when compiling a larger document,  is not something you sit down, complete in one session, and quickly submit. This is especially true when writing for the workplace where accuracy and clarity are necessary. In fact, writing should be seen as a process that is recursive where the writer moves in and out of various stages of writing and often times revisits some of the stages. The writing process might consist of the following:

This is the planning done before writing a document. It may be defining the purpose of the task, analyzing the primary and secondary readers, sketching the document and what will go in each section, or gathering research.

This is writing and compiling a first draft of the document. Sometimes, the writer worries more about getting ideas down more than guaranteeing every punctuation or grammar choice is correct.

When a writer revises, a writer revisits the draft and makes substantial changes to it. This is more than editing. It is adding, deleting, and moving entire sections of the document around to prepare it as a final, comprehensive document. In fact, it is here that many writers ask others for feedback before revising to ensure that another, unbiased set of eyes have looked over the document and easily understand it.

This is the final part of the process. It is reading through the document several times while looking for clarity, consistency, and accuracy. In fact, consider reading your document aloud and listening to it as you do so instead of reading and “seeing” it. Most individuals communicate mostly through talking and listening. Therefore, when you read aloud, you can hear if something in your document doesn’t sound right and then correct it. You should be able to read it in a way that it is understandable and sounds conversational.

For additional information on the writing process, visit The Writing Center website for the University of Texas: University of Texas Writing Center & The Writing Process .

Using a process in the workplace and in our class will strengthen your documents significantly. In fact, remember that your documents reflect on who you are as student, technical writer, employee, and even researcher.

[1] Technical Writing. Authored by : Dr. Elizabeth Lohman. Provided by : Tidewater Community College. Located at : http://www.tcc.edu/ . Project : Z Degree Program. License : CC BY: Attribution , edited by Amber Kinonen , edits included in italics

[2] Use Language that is Sensitive to Your Audience. Provided by : Writing Commons. Located at : http://writingcommons.org/open-text/collaboration/143-common-comments/word-choice-/575-use-language-that-is-sensitive-to-your-audience . License : CC BY-NC-ND: Attribution-NonCommercial-NoDerivatives edited by Amber Kinonen , edits included in italics

[3] Image of Textbook. Authored by : Dominik Wagner. Located at : https://flic.kr/p/eoAvCb . License : CC BY: Attribution

[4] Image of Text with Watch. Authored by : Stephen Wu. Located at : https://flic.kr/p/tZ1LP . License : CC BY-NC-ND: Attribution-NonCommercial-NoDerivatives

[5] Norbert Elliot’s “Labels, Callouts, Captions and Notes” CC-BY Saylor, edited by Amber Kinonen , edits included in italics

[6] The Writing Process CC-BY Amber Kinonen

Chapter 1: Introduction to Technical and Report Writing Copyright © by Bay College is licensed under a Creative Commons Attribution 4.0 International License , except where otherwise noted.

Share This Book

• Advertising
• Applications
• Assessments
• Certificates
• Announcement
• Invitations
• Newsletters
• Questionnaires
• Food & Beverages
• Recruitment
• Marketing Examples
• Transportation

10+ Technical Report Writing Examples – PDF

Technical Report Example

• Google Docs
• Editable PDF

Technical Service Report Example

Free Report Technical Specification

Technical Evaluation Report Letter Example

• Apple Pages

Free Letter of Transmittal for Technical Report

Report Examples:

Technical report writing example.

Parts of a Technical Report Writing

Engineering Technical Report Example

What is a Report used for?

Technical report example format.

Universal Qualities of Technical Report

Report format example.

The Proper Format of a Technical Report

1. the title page., 2. abstract., 3. table of contents., 4. introduction., 5. background theory., 6. theoretical analysis., 7. works cited., 8. appendices., school technical report format.

Technical Report Requirements

Tips in Writing Technical Reports

Types of Technical Reports Writing

General FAQs

1. what is a technical report, 2. what is the purpose of using a technical report, 3. what should a technical report include.

• Abstract and table of contents
• List of illustrations
• Executive summary
• Details you want to share with your client/investors
• Glossary and list of symbols
• Introduction, body, and conclusion of your observation.

4. Why is it important to use a Technical Report?

5. how is a techincal report written.

• Add the title page
• Introduction, highlighting the main aim of the report
• Experiment details and description of budget, if needed
• Results and discussions
• The body, which has details of what you want the reader to know
• Conclude on a positive note.

More Design

9+ formal report examples, 8+ feasibility report examples, 6+ examples of short report, 9+ english report writing examples for students, 5+ ways of writing an observation report examples, 5+ project report examples, what should be in an executive summary of a report, how to write an evaluation report, how to write a short report, 7+ activity report examples.

Related Articles

• id; ?>)" rel="noopener" role="button" tabindex="0" aria-label="postclick">56+ Examples of Report Forms
• id; ?>)" rel="noopener" role="button" tabindex="0" aria-label="postclick">50+ Report Examples

Writing Technical Reports

Writing technical reports #.

In this chapter, you’ll find guidance on writing technical reports . It is mildly opinionated about what technical reports are and should be: the idea is to give you an easy to follow recipe that will produce a pretty strong technical report. As ever with writing, and especially with an output format that is so heterogeneous, there may be good reasons to take a different approach to the one outlined below.

This chapter has benefitted from The Institution of Engineering and Technology’s guide on Technical Report Writing as well as numerous other sources.

Technical reports are fundamentally different to research papers (covered in Writing Papers ) or research blog posts (covered in Research Blog Posts ). In a research blog post or a research paper, the analytical finding (and the narrative around it) is the star of the show; in a technical report, processes and methods are the stars, even though findings may be included. Technical reports are about documenting, well, technical details. They should have enough detail for the reader to understand and perhaps even reproduce the methods under discussion (or know where to start with it).

Another way that technical reports may differ from a research paper is that they can contain the less exciting bits of methodology and process that shouldn’t make it into a paper. This can very much include dead ends, and, in fact, technical reports are as important for what they say about what doesn’t work as what they say about what does.

Tips for Writing Technical Reports #

Zinsser [ 2006 ] and White and Strunk [ 1972 ] are two excellent general resources on writing. Perhaps the first and most important tip is to read one or both of these and take on board their lessons.

Let’s go through some tips that are more specific to technical reports:

Keep the report as short and as concise as possible (while conveying the relevant information). A technical report is not an excuse to waffle and anyone reading it will only be too grateful if they can extract the information without having too wade through too many words.

Organise and signpost the report for the convenience of the reader. That means hyperlinks, decimal numbered sections (for example “1.2.1 Methods”) with clear titles, figure captions, and a structure that follows a logical order. See the next section for a suggested structure.

Include references so that further information is easy to find.

Put charts, tables, and diagrams next to the point in the text where they are first mentioned. If you refer back to them, use a reference, preferably with a hyperlink.

Use vector graphics for pretty much all figures except for photographs. In practice, this means using svg or pdf figures over ones in jpg or png file types. Most visualisation packages will export to multiple file formats, including svg. Later in the chapter, you’ll see how to automate the inclusion of svg charts in a wide range of document formats (yes, even Microsoft Word).

What output format you need to use (docx, markdown, HTML, PDF) will depend strongly on your particular context.

Put the reader first. Do not digress into details that are not relevant to achieving a similar technical outcome. Likewise, although you can include more detail than you would in a paper, you needn’t give the comprehensive history of you have arrived at your knowledge, just the knowledge itself.

Signpost other outputs related to the same project, and do it early. If there’s an accompanying code repository, paper, dataset, or software package, the introduction is probably the place to mention them (you can always give more detail on those additional outputs later in the report if needed).

Structuring a Technical Report #

This is only a suggested structure, and even then only at a high level of detail. To ensure the reader gets sufficient signposting and can quickly and efficiently navigate your technical report, you will probably need to have multiple numbered sub-sections within the sections suggested below.

Title: hopefully this is self evident but if you’re putting multiple outputs in one place (eg on the same landing page of a website), you may wish to warn visitors to your site that this is a technical report by putting ‘Technical Report’ in the title.

Executive Summary: An as-short-as-possible few paragraphs on what, why, who, how, when, outcomes, and where to find further assets (code, data). Having read this, and only this, a reader should have a complete picture of what’s in the rest of the technical report. An executive summary can be longer than an abstract would be for a paper, but the shorter you can make it while conveying the necessary information, the better.

Background or Context: Cover the context of the work, as briefly as possible. Can have, at most, a couple of paragraphs on prior art (don’t bother with a full literature review). If you need to give details on how the report was commissioned that goes beyond what is in the Executive Summary, this is the place.

The sections that make up the body of the report: we now move on to the nitty gritty details. This is where you may wish to have one section or multiple sections, for example, you may want to cover “Methology”, “Data”, “Data Linkage”. What you will cover in the section and sub-section headings will depend on your project, but the key point is to be generous in providing them so that a reader who is skimming the report can find what they’re looking for quickly.

Conclusions: this is a summary of what you have said in the body sections without going over the same ground as the Executive Summary or Background. At the risk of stating the obvious, it is the place to provide, in prose, conclusions on the benefit/effectiveness/difficulty/etc of the methods or processes.

Recommendations: if appropriate (it won’t always be), this section is the place to boil down what you have learned into guidance that others can use. Be aware that some readers may only look at the executive summary and the recommendations. There is nothing wrong with providing your recommendations in a bulleted list to make them easier to digest.

References: the full info on the citations you made in the main piece.

Appendices: try not to have them at all (but sometimes they are necessary). They can sometimes be a good place to put things that aren’t essential to the report but are needed for completeness, for example code showing how something was implemented that is so long it would break up the main report too much.

A Template for Technical Reports #

This section covers how to easily write your technical reports while following all of the best practice detailed in the previous sections. Some of the content is similar to what is in Combining Code and Text in Quarto Markdown .

One of the first choices you need to make when writing a technical report is what tech to use.

You can, of course, just write your technical report in Microsoft Word. This gives you useful features like tracked changes and, for a text heavy document, is not a bad choice. However, there are limitations such as formatting weirdness, difficulties with references, the lack of automation of any code-generated elements, and the lack of easy export to other formats.

The rest of this section introduces an alternative, quarto markdown . This approach is in the spirit of what some people call ‘literate programming’, which mixes code (and code-related approaches) along with writing. Below, there is a quarto markdown template to help you get started.

The advantage of an approach based around markdown is that code-generated elements, references, hyperlinks, formatting, export to other formats, and more, are taken care of, and you can use version control on your report. (These won’t be necessary or even desirable for some reports, but being able to use them if you need is very handy.)

Quarto markdown files have a “.qmd” file extension and look a lot like markdown, or they can be written in a Jupyter Notebook. Vanilla markdown (with file extension “.md”) is the subject of the chapter Markdown , and if you haven’t yet looked at that, you may want to have a quick skim before reading the rest of this chapter. Quarto markdown is a superset of the markdown syntax, the main difference being that quarto has executable code blocks in addition to the usual markdown features.

To create technical reports using quarto markdown, you will need Jupyter Lab (which can be installed using pip install jupyterlab ), an installation of a programme called Quarto , and the other Python packages as used below or for your outputs. For some types of output, you’ll also need to have an installation of the typesetting language LaTeX, for which this book recommends the MikTeX distribution. If you get stuck, the documentation on the Quarto website is very good. (Under the hood, quarto uses pandoc, so you may recognise some commands from pandoc in the below.)

The template below can be put into a Jupyter Notebook (.ipynb file) instead but, as technical reports tend to be text-heavy, we’ll be using a quarto markdown file (with extension .qmd) as the template. To use the template, you can copy the contents below and paste them into a new, empty file called technical_report.qmd which you then open in VS Code.

Once you’ve written your technical report as a quarto markdown file, you can export it using

on the command line. This will produce a Word document. Replace --to docx with --to html or --to gfm or --to pdf to produce HTML, Markdown, or PDF output, respectively. The --wrap=none keyword argument stops the exported markdown having a newline after every link.

Let’s now run through the sections in the template below.

The bit delineated with three dashes is the “yaml” header. This provides various instructions as to how to compile the technical report from qmd to the various output formats. It’s hopefully quite self-explanatory, but there are lines that control:

the name of the Jupyter kernel you want to use to execute the code (run jupyter kernelspec list on the command line to get a list of these)

the name of your bibliography file, using the .bib format

the name of the citation style language file if you’re using one. You can delete this line if you wish and it will just use the default one. If you wish to use the Nature one as in the template, you can find it here but there are .csl files for lots of journals and styles here .

whether to create citations with hyperlinks

whether to have a table of contents

how deep in sub-section titles the table of contents should go

whether to number sections

the format of any images that you are linking to with, for example, the  syntax. SVG is a really strong default choice, so what’s below assumes that images that are included in this way that do not have extensions are SVG files. You can also specify  though.

Next we hit the content, which uses the typical markdown syntax featured in Markdown . In the template below are examples of some of the key features, including:

a citation, @zinsser2006writing where the part after the @ is the key for that entry in your .bib file. How it looks once exported will depend on whether and what csl file you used.

a link, [Coding for Economists](https://aeturrell.github.io/coding-for-economists) , which renders as Coding for Economists

an equation, for example $$ V(x)=\max_{c\in\Omega(x)} U(x,z)+\beta\left[V(x^\prime)\right] $$ , which renders as $ \(V(x)=\max_{c\in\Omega(x)} U(x,z)+\beta\left[V(x^\prime)\right]\) $

code blocks that are static (ie do not get executed), and that begin with backticks and the language, eg ```python

code blocks that get executed, with a toggle ( #| echo: true or #| echo: false ) for whether to include the input code as well as the output. These are deisgnated as ```{python} , ie like the static ones but with the language in curly brackets. The output is typically a chart but it could also be a table ( pandas dataframes get rendered as tables like you’d expect). Note that, by running the magic line matplotlib_inline.backend_inline.set_matplotlib_formats("svg") below, we ensure that the embedded charts are vector graphics even when exporting to Microsoft Word 🔥 🔥 🔥 .

A bit of syntax that generates the bibliography—omitting this will still see a bibliography included, it will just be at the very end instead.

That concludes everything you should need to start creating well-written and structured technical reports with vector graphics, reproducible charts and figures, clearly numbered and signposted sections, equations, code, references, links, a table of contents, and more!