Hardware or Software Products: What Impact on Technical Documentation? Agnès Carchereux, Marion Groix, Amandine Kempf, Harriet Logan, Camille Pépin Master 2 Conception de Documentation Multilingue et Multimédia, Université Paris Diderot-Paris 7, Paris, France Abstract As apprentices in the software, hardware and embedded systems industries, we wondered whether the type of product had an impact on documentation. After collecting the existing literature on the subject, we sent a questionnaire to technical writers with hands-on experience in order to learn more about their methods and skills. Their answers on the subject underlined that having direct access to the product is essential, but that the methods and skills are different depending on the type of product documented. Indeed, for security reasons, hardware industry documents contain more legal requirements than software documents and have a different documentation structure. The type of deliverables and whether the product is published online or in hardcopy depend on how the product is used on site. Terminology and syntax, the illustration workload, and project management methods are also discussed in this article. Keywords: hardware; software; product; documentation; technical writer; embedded products; certification; technical writer’s skill; communication 7,670 words Introduction Technical writing simplifies the complex, translating and tools? Technical writers need to master specific complex topics into simple and accurate discourse so skills: are they different according to the industry? Can that an end user can accomplish a specific task. The writers easily switch from hardware to software? The documentation produced by technical writers includes first part of the article will focus on the information all necessary product information, covering both upon which it is based and on our team organization. operation and maintenance. Technical writing relates to We will then study technical writers’ working methods, any technical field including software (computer and finally, the content of the documentation. programs) and hardware (industrial equipment). This is why, in this research article, we contrast and compare software and hardware documentation. I. Research and methodologies In our current apprenticeships, we mostly document one type of product, be it hardware or software. However, throughout our careers, we are likely to Literature about our subject is scarce and we document both types of products. This was confirmed by encountered difficulties in collecting articles in the a significant number of technical writing professionals at allocated time. Most articles only touch on the subject the International Symposium on Communication that without going into much detail on the differences or similarities of documenting hardware or software was held on January 30th at Paris Diderot University. products. However the literature we found enabled us to Our main concern was thus to study the impact of the go deeper into some topics of the research, and to product on documentation. Do hardware and software confirm or to refute the initial assumptions. The types products require different documentation methodologies of literature we found useful included books, university [1] papers, institution websites, international, regional, or people, including our classmates, the alumni national laws and standards, Subject-Matter Experts association, colleagues and teachers, all of whom were websites, blogs, and conference presentations. encouraged to forward it to anyone who would be Existing literature on laws and standards that govern interested in contributing to our project. A feature on technical writing for the software and hardware the online platform enabled answers to be gathered in a industries is scarce. Some articles elaborate on certain separate spreadsheet, which made it easier for us to standards used in the technical writing world but they analyze and compare them. are neither detailed nor comprehensive. The standards Thirty technical writers answered the questionnaire: of the International Organization for Standardization sixteen of them document software products, nine (ISO) and the International Electrotechnical document hardware products, four document embedded Commission (IEC) are not available online. ISO products, and one creates e-learning materials [Fig.1]. standards are not free; therefore the only way to have The respondents work in different sectors, all of which access to the content is to read articles related to the are highly technical, for instance the medical sector, impact of ISO standards on technical writing. These banking and finance, IT (connected objects, audio articles are usually written by people in the technical equipment, software), or network and messaging writing world who have access to these standards security [Fig.2]. because their companies have purchased them. These Generally speaking, the respondents gave exhaustive articles are usually very short and incomplete, so answers to our different questions. These answers were knowing what these ISO standards contain can be very our most important source of information as they difficult. enabled us to be more accurate. They guided us during Technical writing across domains, a paper written the writing of this paper as they were our only source of by Douglas R. Wieringa and David K. Farkas, deals information when Internet searches failed us. Moreover, directly with this question. The software industry has the diversity of profiles provided a unique source of significantly evolved since the publication of the firsthand experience which allowed us to have a clearer paper in 1991. Nevertheless, we investigated the same idea of the influence of the product on its aspects of the subject, namely the organization of documentation. technical documentation teams, the single sourcing This research article is based on an analysis of the methods, the terminology and phraseology techniques, answers to our questionnaire, Internet research and our and the legal aspects of documentation. Wieringa and own experience as technical writers. It was written Farkas (1991) focused on the comparison between during our apprenticeships, sharing our time between nuclear plant procedures and software documentation. work and university in alternating weeks. This rhythm Their theme is highly technical and only concerns a enabled us to develop the content of our article, taking specialized hardware field. We gave our research a in account our daily experience. Sharing our research broader approach as the diversity of our own work progress with our work colleagues helped us develop experience gave us the opportunity to look at hardware and/or reconsider our content. However, the major issue documentation in general. we had was organizing ourselves to be able to work In order to overcome this lack of literature, we separately on this project in a coordinated fashion. So designed and sent a questionnaire to several technical as to work efficiently, our solution was to use an online writers who work in various fields and thus have drive to centralize our research. Each one of us was different backgrounds and experience. Thanks to this therefore able to follow the progress of the others, method, we obtained crucial information regarding our develop ideas, share experiences, and correct each subject from a wide range of people. other. We also organized meetings to review the work To create our questionnaire, we drew from our and to set new deadlines. The distribution of the personal work experience. We defined eleven questions workload was decided based on our work experience which covered the entirety of the theme at hand, and our own interests. Once the article was written, namely the types of products documented and each team member proofread the entire article in order deliverables provided, the sectors of activity, whether to harmonize the content. Finally, the article was the writer has hands-on access to the product, the submitted to a native English speaker to ensure the project management methods, the legal aspects of the quality of the language. The comments that arose from documentation, its structure, and the terminology and this multiple proofreading enabled the team to type of illustrations used. All of the questions were scrutinize every argument and to discuss different open and not compulsory, so that the respondents aspects of the article in depth. We realized the could be free in their answers. The questionnaire was importance of coordination methods and that a written both in French and English and hosted on a significant amont of time had to be spent on shared online platform. It was sent to approximately 60 proofreading. [2] E-learning Hybrid 3% 13% Hardware 54% Software 30% Figure 1. Distribution of answers according to the type of product documented Aeronautics Training 3% Legal 3% 3% Network security 7% Banking IT 7% 40% Business management 10% Oil/nuclear 10% Medical 17% Figure 2. Distribution of answers according to the sector II. Technical writers’ working method This second part of this article focuses on the it was structured. When a product is updated and the technical writers’ working methods, namely the way documentation needs to be modified, having access to they collect information, their access to the product, the existing documents is key to knowing how the previous project management methods used and the types of product worked and to determining what needs to be deliverables produced.