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
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
182 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
2answers
714 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
133 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
102 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
162 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
345 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
144 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
348 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
90 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
313 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
4answers
95 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
100 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
36 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
117 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
102 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
3answers
840 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
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
430 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
249 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
250 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
132 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
120 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
2k 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
162 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
2answers
88 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 ...
2
votes
1answer
53 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
277 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
112 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
92 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
1answer
124 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 ...
2
votes
2answers
757 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 ...
2
votes
3answers
175 views

How to research and discover topic popularity and trends to determine topic selection for article writing?

I have been asked to write various technical and non-technical articles about computer usage, Windows usage (perhaps some Mac and *nix as well if they let me), Windows repair, and various other ...
2
votes
2answers
133 views

How does one avoid incomplete changes to documentation?

Having encountered errors in technical documentation that almost certainly came from incomplete editing after copying from earlier documentation, I am curious about what techniques can be used to ...
2
votes
1answer
3k views

Mashery vs. Apigee

I was wondering if anyone could lend some advice as to the pros and cons between using Mashery versus Apigee for documenting an API? I have do some evaluating and have about 2 weeks to come up with a ...
2
votes
3answers
83 views

Introducing the next sub-section or not?

I am writing my phd dissertation in a technical field and I have a question. When in the same chapter, I finish a section and want to connect it with the next section I am not sure what is better. ...
2
votes
0answers
46 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
0answers
67 views

How to use His/My/Your permutations in adressing persons [closed]

I'd like to understand the rationale of when, why and how His/My/Your are used in titles of addressing people. For example, the standard commonly accepted uses are: "His Honour"("His Grace", or ...
1
vote
5answers
220 views

What's the best text editor for a technical reference manual?

It is my first time writing tech manuals and I don't know what to use. Some people recommend me LATEX but I think it's too complex. I basically need a text editor that let me: Type latin characters ...
1
vote
4answers
124 views

Is this description of my small productivity application clear enough?

I wrote a small productivity application, Tomate. Since I'm not a native English speaker, I'm afraid the description of the project may not be clear enough for potential users. Can you help me improve ...
1
vote
5answers
84 views

technical subjects - non-fiction vs fiction

This is a question I tried to ask in Novelizing non-fiction, is it worth it? But was un-clear and maybe too generic. Let’s say I am a scuba diving expert and I could write a non-fiction book about ...
1
vote
3answers
144 views

Technical Documentation Voice Preference : “Active Voice” - “Passive Voice” - A Mixture of both

We are working on a technical documentation project which includes the rewriting, modernization, restructuring, enrichment of the content. I'm doing the content rewriting and translation parts of the ...
1
vote
4answers
149 views

How can I express this more clearly or concisely?

I'm documenting a block of computer code and would like to make it clear and concise. I'm describing a function that populates a field on a user input screen. Here's my best shot but it still seems ...
1
vote
4answers
159 views

How to indicate the topic has been changed without using words?

I am writing an an article to share knowledge, not novel. Usually, when you change the current topic, at the beginning of the new paragraph you would like to use some transition words such as ...
1
vote
3answers
155 views

How do I use my blog as a platform for practice and improvement?

I've recently followed the advice of our very own Jeff Atwood and started a blog site in order to become a better writer and communicator. My goal is to improve my skill at technical writing and ...
1
vote
2answers
82 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 ...
1
vote
1answer
412 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 ...
1
vote
1answer
76 views

Multiple tasks and a step by step tutorial

To my knowledge step-by-step tutorials should have the form of a ladder, where you describe how to get to a place step by step– accomplishing a single task at the end. Is it possible to accomplish ...
1
vote
2answers
190 views

What free tools are there to help me improve my English?

I am in the process of writing a research paper in Computer Science. Are there any free tools/browser plugins/web sites/latex plugins that would help me improve my English? I am looking for some nice ...
1
vote
3answers
168 views

Risk Assessment in Technical Standards Documentation

In your experience, are sections on risk and risk management typically part of technical standards documentation? For example, in a document that describes how the Network Time Protocol is ...