Encompasses computer and technology writing, end-user documentation, code documentation, engineering, the sciences, consumer manuals, and more.

learn more… | top users | synonyms

3
votes
1answer
468 views

Path to publishing a technical book

I'm 21 years old female from South India. I would like to publish a book which concentrates on any one latest computer technology. Now, I have completed my BE- Computer Science and Engineering. I'm ...
3
votes
1answer
140 views

What resources will teach me about the state of the art in technical writing?

I've been asked to modernize some technical documentation - user manuals in particular. I have some guidelines, but a lot of free rein to take it in whatever direction I think is worthwhile. Where ...
3
votes
1answer
205 views

Technical writing — best solutions for gathering and compiling data/information

Seek best solutions for information collection, compilation, aggregation Background I'm a newer technical writer working for an industrial fabrication company. We make an awesome B2B product that ...
3
votes
2answers
204 views

Any advice on how to learn DITA for technical writing?

My situation is such that I will be looking for a new job next week as this contract ends. For a tech writer, it is good to have DITA on the ole' resume. So, I just wanted to know if anyone has a site ...
3
votes
1answer
63 views

Is there any research about the efficacy of illustration and example placement in procedure writing?

In writing procedural documentation, I have the choice of writing the complete step-by-step instructions with references to an appendix of illustrations, For instance: 1. Do task 1 (see Fig. 1) 2. ...
3
votes
2answers
343 views

API reference doc: best practices for describing opaque parameters?

The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool ...
3
votes
1answer
442 views

What is the style used in ISO/IEC publications?

I'm in the process of preparing a document to be sent to ISO/IEC WG14. What is the official style used in ISO/IEC publications (if there is one)? If there is no official style guide, is there a ...
3
votes
2answers
139 views

How to create a functional document for in-house reference?

I'm the only technical writer in my company with 2 years of experience. I have been assigned with a task of creating a functional document for a web-based (FMCG) product which has been around a long ...
3
votes
2answers
42k views

Multiple authors in MLA header

I'm writing a group paper and I was wondering whether there's a correct way to list multiple authors at the top of the first page in MLA format. Normally the header would look something like: My Name ...
3
votes
3answers
367 views

How can we make compiling release notes less chaotic?

Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important ...
3
votes
1answer
2k views

How to write time duration correctly

Within a user manual, I need to convey the maximum time period allowed as "365 days 23 hours 59 minutes 59 seconds" - are commas expected between each component? Is the word "and" expected before the ...
2
votes
2answers
185 views

Is this blog post clear and coherent?

I wrote a pseudo-technical blog post trying to apply some game theory concepts to s/w startup industry. This is my first serious attempt at tech blog writing. Iwas left feeling disappointed by the ...
2
votes
5answers
102 views

What is considered an acceptable length for a technical document?

I have written dozens of technical and requirement specifications, and edited dozens more in 8+ years of engineering. The largest I have drafted was perhaps 100 pages, but maybe 30-50% of it was ...
2
votes
3answers
446 views

Use of the Oxford comma

The oxford comma is the second comma in the sentence I like the colors red, white, and blue. Every grammar textbook I've ever seen, as well as the major style guides, feels that this is "proper" ...
2
votes
2answers
182 views

Documenting Agile Sprints

I'm responsible for documenting a huge ERP - its being changed from an old language to .NET. I'm the only one responsible for documenting ( and I'm doing it off-site - the developers' office is an ...
2
votes
2answers
1k views

Present tense in user manuals

I am writing a user manual for an IT system. And inside the user manual I have sentences such as: Users can delete Servers that do not have Customers assigned to them. Is the use of ...
2
votes
2answers
140 views

What are “industry leading royalties”?

In the breakdown description I received from a publisher, they mention that they also pay industry leading royalties of ##%. What does that mean?
2
votes
3answers
120 views

How to find the balance between research and the obvious

I'm embarking on writing my first popular science book on a controversial subject. For sure the writing must be rational, coherent with a clear train of thought and littered with references to be ...
2
votes
3answers
2k views

When should I use italics in scientific writing?

I noticed that proper nouns, such as names of theorems or techniques are often set in italics in scientific writing but not always. Are there rules about it, for example each proper noun should be set ...
2
votes
3answers
204 views

Thesis writing: how to address “self”

This came up when I was writing my thesis: Usually it is recommended that when writing a thesis, one sticks to passive voice and use sentences that read like "The study showed the effect that blah ...
2
votes
1answer
625 views

Can I use the same figure twice in a report?

Is it alright to use the same figure twice (but different figure number) in a report? If so, do I have to use separate captions, to avoid confusion in the table of figures?
2
votes
3answers
148 views

Would it be weird if I write “a simple sample something”?

Not getting too technical, I am writing a configuration file for a piece of software I have developed. This software allows others to write "services" and attach them to my software. I have written a ...
2
votes
3answers
379 views

Should Game Genre Types Be Capitalised?

I am currently writing a report for college about computer games and I am wondering whether genres need to be capitalised. Usually I do not but for some reason it just feels that I should. For ...
2
votes
3answers
153 views

How to structure a sentence containing long code examples?

In the context of a technical manual, I need to write instructions guiding users through several standard manipulations. When providing examples of these manipulations, I have written a short sentence ...
2
votes
4answers
480 views

How to reference a figure from text in a technical document

I'm preparing technical documentation for some software. For the installation, there are lots of screen grabs and they all have Figure x captions. What's the correct styling and means of referencing ...
2
votes
1answer
649 views

What are best practices when writing technical descriptions?

Occasionally, in my job as an engineer, I write process descriptions of the technology we are selling. Those are part of commercial offers, intended to win the customer. Those are bundled with ...
2
votes
4answers
96 views

Advice on interface text in a videogame

[This fits somewhere between technical writing and user experience, so perhaps this is the wrong board] I'm developing a modification to a popular videogame (a Playstation One RPG), with the ...
2
votes
1answer
102 views

Resources for thesis writing

Will be writing my master's thesis in a few months. I have never written a thesis yet though. I was unlucky enough not to be required to have a thesis during my undergrad years. Anybody know some good ...
2
votes
2answers
39 views

Ethics of incorporating a supplier's technical documentation into one's own documentation?

A company, M, buys components from company, S, to build into their product. Company S has technical documentation regarding safety and maintenance available in many languages and publicly available in ...
2
votes
3answers
154 views

Ending a PhD thesis by saying “there is more to do”

I am ending the conclusion of my PhD thesis by saying something like this (not even remotely in these words): There was a lot of work gone in the thesis, yada yada yada, however there is room for ...
2
votes
2answers
134 views

Template for IT technical report?

I'm looking for a template or guidelines for how to write a technical report. The report is IT-related and intended for a project manager to review the work of the investigation of a IT-related ...
2
votes
4answers
2k views

What are the tool choices for producing technical documentation in PDF and web site ready HTML?

My company currently maintains our technical documentation (User's Guide) in Google Docs. With each release I produce a PDF that we host on our website. Here are the features of Google Docs that work ...
2
votes
1answer
543 views

In what narrative mode should you explain a process or task?

I want to explain a psychological and behavioural process to someone via email. I start off in first-person and speak to them in second-person, but what do I use when I want to explain a process ...
2
votes
1answer
260 views

Using Glossary Instead of Footnotes (for translation/transliteration)

I am writing a technical report with keywords which are mainly English. I am using a Glossary at the end, which describes translated keywords. Is it a replacement for footnotes or I should just keep ...
2
votes
2answers
267 views

List of figures and diagrams?

I was wondering what is the most acceptable way of including a large diagram in my thesis. The diagram takes up a full page and splits a paragraph. In your opinion is this bad? Should I put the ...
2
votes
1answer
81 views

Graphical presentation method nomenclature

I'm part of a technical documentation team where I'm suggesting the document designers different methods for graphical presentation. Each time I need to talk about a method I have to look around and ...
2
votes
1answer
239 views

Use of Registered trademark

I'm writing a book on Windows and I need some guidelines. On the cover of the book, as part of the subtitle, may I include Windows® in it? Inside the book, do I have to use the ® every single little ...
2
votes
1answer
172 views

Metrics for assessing the persuasiveness of a paper?

Are there any known variables to measure, or questions to ask in survey, in order to asses the persuasiveness of a paper? For example, I'm not sure if omitting a section from my paper might actually ...
2
votes
1answer
128 views

How to combine a visual and textual outline

I am a Ph.D. student in engineering, so most of my writing fits into a fairly strict idiom: the IMRaD (Introduction, Methodology, Results, and Discussion). In general, I like to use an outline to help ...
2
votes
1answer
3k views

APA (sixth edition) citation for the Fourth Assessment Report

I'm trying to cite a source from the IPCC Fourth Assessment Report: http://www.ipcc.ch/publications_and_data/publications_and_data_reports.shtml I'm fairly new to APA in general and I'm struggling to ...
2
votes
1answer
166 views

How should be the format for literature references that are websites (URLs)?

In technical writings are good established standards for formatting literature references. But that doesn't work this well for URLs. How should these references be formatted?
2
votes
1answer
32 views

Should I use figure titles for diagrams on the web?

Should I use figure titles for diagrams in web content if the diagram already has a caption? Guidance or references are appreciated. The context is a marketing page whose basic structure is shown in ...
2
votes
1answer
80 views

Is the Microsoft Manual of Style appropriate for writing general IT related instructional documents?

I'm currently working for a company's IT department, and one of my tasks is to write documentation for common procedures that we perform, in order to get new employees acquainted with them more ...
2
votes
1answer
391 views

Can Google Docs be used for technical product documentation?

My company is hiring a contract technical writer to improve our product's documentation. As the maintainer, I'm currently using Google Docs, and very happy with it's collaborative nature (multiple ...
2
votes
2answers
120 views

How to represent dependencies in outlines

The bulk of my writing consists of technical papers, reports, notes, and memos. Because of the mathematical nature of my work I spend a lot of time writing definitions, and it is very important that I ...
2
votes
1answer
82 views

Ways to influence the readers subconscious?

Are there any proven techniques of influencing the readers on a subconscious level? Preferably techniques involving only words as I'm interested in writing technical books and I don't have the liberty ...
2
votes
2answers
50 views

Wording of comparing X vs Y and X vs Z but not X vs Y vs Z

As per the title I compared my system against two other systems separately but I'm worried about it coming across as that it was a three way comparison. Neither of the below titles convey what I want ...
2
votes
2answers
100 views

Authoring tool for interactive documentations

I am searching for an application (Desktop- or Web-App) to write and create interactive documentation (especially technical documentation). I like Madcap Flare for technical writing, but I'm looking ...
2
votes
1answer
974 views

What is Content Testing?

What is Content Testing? Are there content testing tools available, or is content simply tested manually for quality?
2
votes
2answers
1k views

What software is good for writing a technical book? [duplicate]

I must write a book for the university and I am looking for software. The style that I want is like the books of O'Reilly, Apress or Packt. I need: Insert a table of contents (automatic). Divide ...