Common Technical Writing Issues

Tao Xie

2006-01-01

Abstract:• Check your writing to see whether there is “This is”“It is”“They are”“This does”… and fill in a noun after “this” or “that”, and replace “they”.. with a noun.• Bad: The solution in Fig. 2 is in fact a graph production. It follows the definition and presents a software transformation rule.

What problem does this paper attempt to address?

Improving Natural Language Requirements Quality Using Workflow Patterns

Ye Wang,Xiaohu Yang,Cheng Chang,Aleksander J. Kavs

DOI: https://doi.org/10.1587/transinf.E96.D.2065

2013-01-01

IEICE Transactions on Information and Systems

Abstract:Natural language (NL) requirements are usually human-centric and therefore error-prone and inaccurate. In order to improve the 3Cs of natural language requirements, namely Consistency, Correctness and Completeness, in this paper we propose a systematic pattern matching approach supporting both NL requirements modeling and inconsistency, incorrectness and incompleteness analysis among requirements. We first use business process modeling language to model NL requirements and then develop a formal language - Workflow Patterns-based Process Language (WPPL) - to formalize NL requirements. We leverage workflow patterns to perform two-level 3Cs checking on the formal representation based on a coherent set of checking rules. Our approach is illustrated through a real world financial service example - Global Equity Trading System (GETS).
How to be an Effective Technical Writer?

M Solaiman Ali,Dheya Al-Othmany

DOI: https://doi.org/10.3991/ijep.v2i3.2094

2012-07-06

International Journal of Engineering Pedagogy (iJEP)

Abstract:Abstract--This paper has focused on technical writing as a skill for engineers. It has sought to define technical writing and throw light on the content and technique of writing the various components of successful technical reports (for example, articles, papers, or research reports, such as theses and dissertations). Then, it has highlighted other special features and principles of effective technical writing. The material in this paper is divided into seven major parts. Part 1 (Technical writing for engineers) stresses that a successful engineering career requires strong writing skills. Part 2 (How to write the major sections or elements of a report) describes the techniques of writing the abstract, introduction, literature review, procedure/methods & materials, results, discussion, conclusion, and recommendations. Part 3 (Special features of technical writing) brings into focus some of the special features of technical writing such as tables & graphs in the text, graphics in instructions, team writing, ethics (plagiarism), document sources, three citation styles and IEEE reference style. Part 4 (Technical usage) deals with writing abbreviations, initialisms and acronyms, numbers, units of measurement, and equations.Part 5 (Technical style) highlights the imperative writing style and other features of technical writing such as the use of active and passive voices, plain vs. complex syntax, avoiding redundant or superfluous expressions, and vague generalities, using words or expressions with visual impact, the past tense to describe experimental work, the present tense to describe hypotheses, principles, theories and truths, and breaking up the text of the report into short sections. Part 6 (Document specifications) emphasizes the technical writer’s need to conform to such document specifications as word count, format, font, number of words per line of text imposed. Part 7 (Reader-friendly technical writing) suggests choosing the varied writing modes (patterns of organization of information) to suit the technical writing task, checking for technical accuracy and following three levels of editing to help increase the readability of a technical text. Finally, in part 8 (Ethical/legal considerations for the technical writer), the authors suggest ways for the technical writer to overcome ethical/legal dilemmas on the job.
The ABC of academic writing: non-native speakers’ perspective

Shinichi Nakagawa,Malgorzata Lagisz

DOI: https://doi.org/10.1016/j.tree.2024.01.008

IF: 20.589

2024-02-01

Trends in Ecology & Evolution

Abstract:Academic writing is difficult, especially for non-native English speakers. We share a perspective on writing with a set of heuristics called the Writing Alphabet, consisting of Accurate, Brief, Clear, Dynamic, Engaging, Flowing, Goal, Habit, and Investment. These points can help struggling writers identify issues and, importantly, internalise good writing practices.

genetics & heredity,ecology,evolutionary biology
Teaching Writing and Communication in a Mathematical Modeling Course

Jean Marie Linhart

DOI: https://doi.org/10.1080/10511970.2014.895459

2014-06-18

PRIMUS

Abstract:Writing and communication are essential skills for success in the workplace or in graduate school, yet writing and communication are often the last thing that instructors think about incorporating into a mathematics course. A mathematical modeling course provides a natural environment for writing assignments. This article is an analysis of the type of writing assigned in my mathematical modeling course. Where the assignments are unusual, they are thoroughly described and I share my experiences on what worked well and what was not as successful. Where the assignments are more traditional, I offer an analysis of problems and pitfalls in teaching writing. Formal project reports for the class teach students how to write scientific articles. Unusual reflective assignments help students integrate their learning and apply it in new contexts.
Problems and Solutions of Colleges Common Code Management

Xie Suping,Chen Huaichu,Zou Xiangrong,Yin Shixue

DOI: https://doi.org/10.1109/itme.2015.113

2015-01-01

Abstract:This document analyzes the problems of college common code management, proposes standardized methods to unify common code and builds a management system, which can support the multiple version of common code and archive the history tracing of common code data.
On Some Problems about Protection Setting Calculation Software

Hui-fang WANG

DOI: https://doi.org/10.3969/j.issn.1674-3415.2006.12.004

2006-01-01

Abstract:The status of setting calculation software is detailed.The problems are pointed out,such as the validity of calculation results,usability,universality and developability of software.The methods to solve these problems are four steps.First,it takes operating condition as the combination of running mode of plant or station,power supply topological and rules of equipment maintenance.It is useful at simplifying setup and choice of operating conditions and ensuring calculation result correction.Second,the functions of achieving integrated setting list is offered,setting examination and rectification are setting to enhance software's practicality and interaction design method is employed to ensure software's usability.Third,it introduces software structure with insert mode to actualize the common platform.With this structure,the software can be used in various levels of power networks by switching function groupware with corresponding edition.It is important to solve software' universality.Fourth,the theory of software engineering is studied and the management of development course is strengthened to ensure the developability of software.
Identifying TraIn

Xiao Wang,Lu Xiao,Ye Yang,Xinyi Xu,Yu Jiang

DOI: https://doi.org/10.1145/3183440.3195008

2018-01-01

Abstract:Socio-Technical Congruence (STC) indicates that social interactions among developers should be congruent with technical dependencies among their tasks. Prior research discovered that the lack of the "should-happen" communication will lead to integration errors and productivity decrease. However, the opposite scenario, excessive communication not matched by any technical dependencies, has been largely neglected. This paper terms such scenario as Transgressive Incongruence (TraIn). To automatically pin-point source files involved in TraIn, this paper defines a new form of coupling between files, called communication coupling. It measures the communication traffic among developers working on two files. Evaluation on 6 Apache open source projects reveals: 1) the communication coupling between files with structural dependencies is 3 to 10 times higher than that between files independent from each other; and 2) source files involved in TraIn are usually very bug-prone. This implies that TraIn may have negative impact on the quality of software systems, and thus should merit due attention.
Solution of Technical Contradiction for Dependable Software Based on QFD and TRIZ

Xiaotun WANG,Wei XIONG

2011-01-01

Abstract:In order to improve software dependability,a method is proposed for solving technical contradictions in dependable software development based on quality function deployment(QFD) and the Russian theory of inventive problem solving(TRIZ).First,a dependable software planning house of quality(HOQ) is built to introduce the voice of customers into the software development process.Then,the technical characteristic pairs whose relationships are negative in the technical correlation matrix are found out and analyzed in detail.The inventive principles of TRIZ are applied to solve the technical contradictions,and several feasible solutions or inspirations could be acquired.Considering the vagueness and uncertainty of expert judgment,and the case of multi-granularity and multi-semantics in an expert's linguistic statement,the linguistic information decision-making theory developed in recent years is introduced to evaluate and select the best feasible alternative.Finally,a real-world case of astronautics of an embedded real time operating system(ERTOS) software development is provided to demonstrate the validity and applicability of the proposed method.
Analysis of Common Errors in Financial English-Chinese Translation

Huang Chunqian,Chunqian Huang

DOI: https://doi.org/10.4236/oalib.1107095

2021-01-01

OALib

Abstract:As English for a special purpose, financial English is characterized by its strong professionalism and complex sentence structure, thus leading to many translation mistakes. This paper first introduces the stylistic features of financial English, then points out three common mistakes in financial translation with some corresponding examples. At last, three strategies are being put forward for improving the translation quality of financial English, aiming to promote the effective communication between international finance and foreign trade industries.
Students’ Common Errors in English Essay Writing: an Analysis at Thu Dau Mot University

,Trinh Huynh Chan

DOI: https://doi.org/10.58806/ijsshmr.2024.v3i9n01

2024-09-06

Abstract:Being good at writing essays is super important for students, but it is often made difficult by common errors that get in the way of clear communication. Sometimes, they make common mistakes that can mess up their writing and make it hard to understand. In this article, we are going to talk about these usual mistakes students make when they write essays. We will also explain why these mistakes happen and give some ideas about how to fix them. We will use research, educational knowledge and what teachers know about teaching to help us figure out how these mistakes make essays not so good, and we'll give some easy tips to help students get better at writing. When we look closely at these mistakes, we can learn a lot. By finding out why they happen, we can understand them better and try to avoid them. This article is like a map that guides students and teachers on a journey to better writing. When students and teachers work together, they can fix these mistakes and make writing even better. So, let's explore the world of essay writing, find those pesky mistakes, and develop better writing habits and improve academic writing.
Software Process Commonality Analysis

Alexis Ocampo,Fabio Bella,Jürgen Münch

DOI: https://doi.org/10.48550/arXiv.1312.4742

2013-12-17

Software Engineering

Abstract:To remain viable and thrive, software organizations must rapidly adapt to frequent, and often rather far-ranging, changes to their operational context. These changes typically concern many factors, including the nature of the organization's marketplace in general, its customers' demands, and its business needs. In today's most highly dynamic contexts, such as web services development, other changes create additional, severe challenges. Most critical are changes to the technology in which a software product is written or which the software product has to control or use to provide its functionality. These product-support technology changes are frequently relatively 'small' and incremental. They are, therefore, often handled by relatively 'small,' incremental changes to the organization's software processes. However, the frequency of these changes is high, and their impact is elevated by time-to-market and requirements change demands. The net result is an extremely challenging need to create and manage a large number of customized process variants, collectively having more commonalities than differences, and incorporating experience-based, proven 'best practices'. This paper describes a tool-based approach to coping with product-support technology changes. The approach utilizes established capabilities such as descriptive process modeling and the creation of reference models. It incorporates a new, innovative, tool-based capability to analyze commonalities and differences among processes. The paper includes an example-based evaluation of the approach in the domain of Wireless Internet Services as well as a discussion of its potentially broader application.
Technical Dimensions of Programming Systems

Joel Jakubovic,Jonathan Edwards,Tomas Petricek

DOI: https://doi.org/10.48550/arXiv.2302.10003

2023-02-20

Programming Languages

Abstract:Programming requires much more than just writing code in a programming language. It is usually done in the context of a stateful environment, by interacting with a system through a graphical user interface. Yet, this wide space of possibilities lacks a common structure for navigation. Work on programming systems fails to form a coherent body of research, making it hard to improve on past work and advance the state of the art. In computer science, much has been said and done to allow comparison of **programming languages**, yet no similar theory exists for *programming systems*; we believe that programming systems deserve a theory too. We present a framework of *technical dimensions* which capture the underlying characteristics of programming systems and provide a means for conceptualizing and comparing them. We identify technical dimensions by examining past influential programming systems and reviewing their design principles, technical capabilities, and styles of user interaction. Technical dimensions capture characteristics that may be studied, compared and advanced independently. This makes it possible to talk about programming systems in a way that can be shared and constructively debated rather than relying solely on personal impressions. Our framework is derived using a qualitative analysis of past programming systems. We outline two concrete ways of using our framework. First, we show how it can analyze a recently developed novel programming system. Then, we use it to identify an interesting unexplored point in the design space of programming systems. Much research effort focuses on building programming systems that are easier to use, accessible to non-experts, moldable and/or powerful, but such efforts are disconnected. They are informal, guided by the personal vision of their authors and thus are only evaluable and comparable on the basis of individual experience using them. By providing foundations for more systematic research, we can help programming systems researchers to stand, at last, on the shoulders of giants.
No Automated Writing System, No Efficient Writing Training

Tao DING,Yong-lin YANG

DOI: https://doi.org/10.3969/j.issn.1009-8097.2016.02.013

2016-01-01

Abstract:A challenge writing instructors have to face is how to improve writing teaching more efficiently in the “Internet Plus” era. Based on the teaching experience, our answer was to the direction of resource utilization and intelligence. Following this line of reasoning, the iSmart-Teaching Resources Platform (iSmart-TRP Version 3.1) was introduced by illustrating its merits in intelligent resource-dispatching, error-correcting and composition-commenting. It is concluded that the problem of reducing teaching cost and improving teaching quality cannot be solved without the support from teaching resources and information technology.
Automated Inconsistency Analysis of Real-Time Requirements: A Domain Expert Friendly Approach.

Shaobin Liu,Xiaohong Chen,Zhi Jin,Min Zhang

DOI: https://doi.org/10.1109/hpcc-dss-smartcity-dependsys57074.2022.00175

2022-01-01

Abstract:Many safety-critical systems need to meet increasing real-time requirements, which asks for formal inconsistency analysis. However, most of the current formal approaches are unfriendly to domain experts. It is a heavy burden for them to formalize the natural language requirements and use formal methods to analyze the inconsistency. To help the domain experts, in this paper, we define a real-time requirements pattern language, and propose an automated real-time requirements inconsistency analysis approach based on constraint solving. A case study on automotive lighting systems shows the feasibility of our approach.
[Analysis on the Common Failures of Spiral CT Systems and Their Solutions].

De-Hua He,Bin Li

DOI: https://doi.org/10.3969/j.issn.1671-7104.2006.02.023

2006-01-01

Abstract:According to the structural characteristics of spiral CT systems and our experiences, some relevant solutions to common malfunctions in daily maintenance are suggested.
The Generic Framework of Software Based on XML

Jing SUN,Ying LIU,Jingtao MENG,Wei LI

DOI: https://doi.org/10.3969/j.issn.1003-3106.2015.06.07

2015-01-01

Radio Engineering

Abstract:There are great varieties of devices in aerospace TT&C system,the data interaction protocol between devices are different, complex and frequently changed,which introduces great difficulties in software management,this paper provides a solution to realize the general framework of TT&C software.The format of XML files is introduced,the interface characteristic of aerospace TT&C software is analyzed,and a configurable, interface changeable TT&C application framework which is based on XML files is put forward. This framework has already been applied to the TT&C system, and significantly improves the efficiency and the accuracy of the software development process.
They, Them, Theirs: Rewriting with Gender-Neutral English

Tony Sun,Kellie Webster,Apu Shah,William Yang Wang,Melvin Johnson

DOI: https://doi.org/10.48550/arXiv.2102.06788

2021-02-12

Computation and Language

Abstract:Responsible development of technology involves applications being inclusive of the diverse set of users they hope to support. An important part of this is understanding the many ways to refer to a person and being able to fluently change between the different forms as needed. We perform a case study on the singular they, a common way to promote gender inclusion in English. We define a re-writing task, create an evaluation benchmark, and show how a model can be trained to produce gender-neutral English with <1% word error rate with no human-labeled data. We discuss the practical applications and ethical considerations of the task, providing direction for future work into inclusive natural language systems.
English for Electrical Engineering and Automation: Features and Translation Approaches

Ling Zichen

Abstract:Electrical engineering and automation is critical in industry in various forms. This paper intends to discuss lexical and syntactical characteristics in professional English. The analyses specifically include abbreviations,meaning for specialized word,division of sense group,correct translation of sentences in professional terms,word order adjustment as well as long sentence translation.

Engineering,Linguistics,Computer Science
Study on Common Problems in Engineering Graphics

YANG Pei-zhong

DOI: https://doi.org/10.3969/j.issn.1671-7775.2006.05.013

2006-01-01

Abstract:The two common problems in engineering graphics are studied,which are: ①the characteristic points on the intersection of a cylinder and a cone with their axes intersecting perpendicularly and ② the principal axis of the V-projection ellipse of the intersection of an oblique plane and a cylinder.The commonly wrong solutions are discussed and the right solutions are derived by using conic theory.At last the graphic methods for the problems are given.engineering graphics;intersection;conic;graphic method
Common sense computing (episode 4): debugging

Beth Simon,Dennis Bouvier,Tzu-Yi Chen,Gary Lewandowski,Robert McCartney,Kate Sanders

DOI: https://doi.org/10.1080/08993400802114698

2008-06-01

Computer Science Education

Abstract:We report on responses to a series of four questions designed to identify pre-existing abilities related to debugging and troubleshooting experiences of novice students before they begin programming instruction. The focus of these questions include general troubleshooting, bug location, exploring unfamiliar environments, and describing students' real life troubleshooting experiences. We find that the common sense experience of students related to debugging is often at odds with the needs for debugging programs. Student troubleshooting experiences recognize real world non-determinism and rarely require undoing an attempted fix. Based on student answers, we shed light on some specific frustrations of instructors and make a set of recommendations for teaching, including addressing the difference between finding an error and fixing it, modeling the formation of multiple hypotheses, and encouraging students to apply domain knowledge.

Common Technical Writing Issues

Improving Natural Language Requirements Quality Using Workflow Patterns

How to be an Effective Technical Writer?

The ABC of academic writing: non-native speakers’ perspective

Teaching Writing and Communication in a Mathematical Modeling Course

Problems and Solutions of Colleges Common Code Management

On Some Problems about Protection Setting Calculation Software

Identifying TraIn

Solution of Technical Contradiction for Dependable Software Based on QFD and TRIZ

Analysis of Common Errors in Financial English-Chinese Translation

Students’ Common Errors in English Essay Writing: an Analysis at Thu Dau Mot University

Software Process Commonality Analysis

Technical Dimensions of Programming Systems

No Automated Writing System, No Efficient Writing Training

Automated Inconsistency Analysis of Real-Time Requirements: A Domain Expert Friendly Approach.

[Analysis on the Common Failures of Spiral CT Systems and Their Solutions].

The Generic Framework of Software Based on XML

They, Them, Theirs: Rewriting with Gender-Neutral English

English for Electrical Engineering and Automation: Features and Translation Approaches

Study on Common Problems in Engineering Graphics

Common sense computing (episode 4): debugging