Technical writing style guide Style guides help you write different kinds of content, such as API documents, writing an overview of complicated technical products, or explaining how to use a product. Sometimes, these describe the ways to adapt the content based on your audience Best technical styleguide for navigation: Google Developer styleguide. As any technical writer knows, when you have a lot of information to present, organization is key. The Google Developer styleguide solves the organization problem by keeping the reader in mind throughout Welcome to the Microsoft Writing Style Guide, your guide to writing style and terminology for all communication—whether an app, a website, or a white paper. If you write about computer technology, this guide is for you. Today, lots of people are called upon to write about technology
Technical Writing Guidelines | DigitalOcean
Get the latest tutorials on SysAdmin and open source topics. Hub for Good Supporting each other to make an impact, technical writing style guide. Write for DigitalOcean You get paid, we donate to tech non-profits. By Hazel Virdó and Brian Hogan. DigitalOcean is excited technical writing style guide continue building out its collection of technical articles related to server administration and software engineering. To ensure that DigitalOcean articles have consistent quality and style, we have developed the following guidelines.
To get published quickly, we recommend that you read the Style and Structure technical writing style guide in their entirety before you begin working on your article.
You can use the Formatting section of this guide along with our Markdown previewer as references while writing your article. We also have a technical best practices guide which outlines our tech-focused recommendations.
We have developed article templates in Markdown format you can use as a starting point for your article. We strongly recommend using one of these templates to plan and develop your article. Instead, technical writing style guide, we strive to ensure all DigitalOcean tutorials are:. These principles guide authors to create articles, tutorials, and other learning materials that help people solve their problems and grow as developers. We explicitly include every command a reader needs to go from their first SSH connection on a brand new server to the final, working setup.
We also provide readers with all of the explanations and background information they need to understand the tutorial. The goal is for our readers to learn the concepts, not just copy and paste code and commands. Instead, we encourage our readers by providing the explanations they need to be successful. Our articles are technically accurate and follow industry best-practices, technical writing style guide.
They also provide more details than just the code and commands. We provide all the details necessary for the readers to understand it, technical writing style guide. Every command should have a detailed explanation, including options and flags as necessary.
Every block of code should describe what it does and why it works that way. These details give readers the background they need to grow their skills. Authors test their tutorials to ensure they work by following them exactly as written on fresh servers. This ensures accuracy and identifies missing steps. Our editors also test these articles as part of the review process to ensure a great learning experience for the reader. Once a reader has technical writing style guide a DigitalOcean article, they should have installed, built, or set up something from start to finish.
We emphasize a practical approach: at the end of an article, the reader should have a usable environment or an example to build upon. What this means for the writer is that their article should cover the topic thoroughly.
Authors should link to existing DigitalOcean articles, if available, to set up prerequisites that readers should follow before beginning the tutorial, and link to available DigitalOcean articles to provide additional information in the body of the tutorial. Our tutorials aim for a friendly but formal tone. This means that articles do not include jargon, memes, excessive slang, emoji, or jokes. Unlike blog posts, we do not use the first person singular e.
Instead, we encourage the use the second person e. Technical writing style guide encourage motivational language focused on outcomes. This motivates the reader and focuses on the goal they need to accomplish. Finally, the language of our tutorials honors diverse human experiences and follow our Community Code of Conduct. That means we avoid offensive language or other content that is in reference to but not limited to age, disability, ethnicity, gender identity or expression, level of experience, nationality, neurodiversity, personal appearance, race, religion, political affiliation, sexual orientation, socioeconomic status, or technology choices.
DigitalOcean articles have a consistent structure, technical writing style guide includes an introduction, a conclusion, technical writing style guide any prerequisites necessary for a reader to get started. However, the specific structure depends on the type of article.
Procedural tutorials walk the reader through accomplishing a complex task. The structure for one of these articles looks like this:. Those articles will have a structure like this:. Our article templates have this structure already written for you in Markdown, and we encourage you to use these templates as a starting point for your own articles.
When you write your title, think carefully about what the reader will accomplish by following your tutorial. Try to include the goal of the tutorial in the title, not just the tool s the reader will use to accomplish that goal. For example, if your tutorial is about installing the Caddy web server, the goal is likely to host a website. If your tutorial is about installing FreeIPA, the goal might be to set up centralized Linux authentication. The first section of every article is the Introductionwhich is usually one to three paragraphs long.
The purpose of the introduction is to motivate the reader, set expectations, and summarize what the reader will do in the article, technical writing style guide. Your introduction should answer the following questions:. Keep the focus on the reader and technical writing style guide they will accomplish. This goes a long way to motivate the reader and get them excited about your topic. In addition, keep the focus on the problem the reader is solving rather than the technology.
For example, if a tutorial is about building a project with React, you can focus your technical writing style guide on the project rather than explaining what React is and its history. You should only use this section if your tutorial requires multiple servers, has a large software stack, technical writing style guide, or otherwise has a particularly complicated purpose, method, or result. The Prerequisites sections of DigitalOcean articles have a very specific format and purpose.
The purpose is to spell out exactly what the reader should have or do before they follow the current tutorial. The format is a bulleted list that the reader can use as a checklist, technical writing style guide. Each bullet point must link to an existing DigitalOcean tutorial that covers the necessary content if one exists.
This allows you to rely on existing content known to work instead of starting from scratch. Our systems and DevOps tutorials take the reader from a fresh deployment of a vanilla distribution image to a working setup, so they should start with the first SSH connection to the server or include a prerequisite tutorial that does. For example, a tutorial about building and deploying a Node. js application and deploying it to an Ubuntu server using Git might have the following prerequisites:, technical writing style guide.
By reading the prerequisites, technical writing style guide, your reader knows exactly what they need technical writing style guide do before they start. There are no surprises. When you test your tutorial, make sure you follow all of the prerequisite tutorials exactly as written, so that everyone uses the same starting point. If you changed a variable or completed an optional step from one of the prerequisites, make sure to note that.
Ubuntu React-based web development projects by looking at How To Build a Photo Search App with React Using the Unsplash API. Be specific with your prerequisites. Instead, technical writing style guide, consider listing specific concepts the reader should technical writing style guide, and provide them with resources that help them get up to speed so they can successfully complete your tutorial. The Step sections are the parts of your tutorial where you describe what the reader needs to do.
Each step begins with a level 2 heading and use the gerund, which are -ing words. Procedural tutorials should start each step title with the word Step and a number, followed by an em-dash:. After the title, add an introductory sentence that describes what the reader will do in each step and what role it plays in achieving the overall goal of the tutorial.
Focus on the reader. End each step with a transition sentence that describes what the reader accomplished and where they are going next. All commands a reader must run should be on their own line in their own code block, and each command should be preceded by a description that explains what the command does.
After the command, you should provide additional details about the command, such as what the arguments do and why your reader is using them. The -a switch shows all files, including hidden ones, and the -l switch shows a long listing including timestamps and file sizes.
You should display the output of commands and programs using a separate code block, like in the following example:. Note that the output block has a label and is separated from the command with some text that explains the output. Separating the commands from the output makes it more clear to readers where the command ends and the output begins.
Like commands, always introduce a file technical writing style guide script by describing its general purpose, then explain any changes that the reader will be making in the file. On tutorials that are targeted at command-line users, instruct the reader to create and open the file using a command on its own line:. We use vi on tutorials for CentOS and FreeBSD.
In all cases, avoid using touch to create new empty files, technical writing style guide, as your readers can create files with the editor directly instead.
For tutorials where the reader is not expected to use the command-line interface, such as front-end development tutorials, you can omit the command to open the file.
However, be sure technical writing style guide tell the reader which file to open explicitly:. Then show the code, and then call out any important details. The console. log function takes a string and prints it to the screen on its own line. When you do this, show the relevant parts of the file and use highlighting to make it clear what should change:.
This Docker Swarm tutorial is a good example technical writing style guide how to use our custom Markdown to distinguish between commands run on several different servers, as well as locally. The Conclusion of your tutorial should summarize what the reader has accomplished by following your tutorial. The conclusion should also describe what the reader can do next. This can include a description of use cases or features the reader can explore, links to other DigitalOcean tutorials with additional setup or configuration, and external documentation.
DigitalOcean tutorials are formatted in the Markdown markup language.
TECHNICAL WRITING STYLE-Business Communication HUM400 LECTURE 12
, time: 1:07:47Using a Style Guide for Technical Writing (in )
Microsoft Manual of Style (4th Edition) – Probably the most commonly used reference guide for technical writers. Here’s the blurb: “Direct from the Editorial Style Board at Microsoft—you get a comprehensive glossary of both general technology terms and those specific to Microsoft; clear, concise usage and style guidelines with helpful examples and alternatives; guidance on grammar, tone, and voice; and best Technical writing style guide Style guides help you write different kinds of content, such as API documents, writing an overview of complicated technical products, or explaining how to use a product. Sometimes, these describe the ways to adapt the content based on your audience Best technical styleguide for navigation: Google Developer styleguide. As any technical writer knows, when you have a lot of information to present, organization is key. The Google Developer styleguide solves the organization problem by keeping the reader in mind throughout
No comments:
Post a Comment