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

learn more… | top users | synonyms

0
votes
1answer
23 views

Footnote placement — inside or outside terminal quote?

When you are referencing inforamtion in the footnote, is it customary to put the footnote number inside the quote or outside? For instance is it: "The pink pig."1 or: "The pink pig.1"
0
votes
2answers
32 views

Can you use et al. in a Bibliography?

In the text, I have, e.g. "...a major role to play in role-playing (Smith et al., 1990)." But can I use the same abbreviation in the bibliography? Smith, K. et al. 1990. Playing major roles ...
0
votes
1answer
23 views

How to cite a report in APA style

I have been trying to go through Mayfield Book on Technical Writing to find out how to do an in-text and parenthetical citation of a source that I found online. The source looks like a report with ...
1
vote
1answer
38 views

Citing an article with multiple authors in APA style

I have been trying to go through Mayfield Book on Technical Writing to find out how to do an in-text and parenthetical citation of a source that I found online. The source is an article from a popular ...
0
votes
1answer
66 views

What is it called when an author uses vague words for concrete concepts, “hedging”?

As an editor for an academic press, my pet peeve is when authors write sentences like "attempt to conceive of a possible approach to resolve X" instead of "try to resolve X". Obviously one big ...
2
votes
3answers
97 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 ...
1
vote
5answers
76 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 ...
0
votes
3answers
38 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 ...
6
votes
4answers
111 views

The fine line between accurate science, and confusing my reader

I recently wrote a blog post (original here) about a scientific study. At the end, I included some "fine print" which states, among other things: Correlation does not mean causation. It’s ...
2
votes
1answer
60 views

What is Content Testing?

What is Content Testing? Are there content testing tools available, or is content simply tested manually for quality?
0
votes
1answer
42 views

How to change Microsoft Word Heading style [closed]

For example, Heading 1 is automatically typeset as Chapter 1: Chapter 1 Title. I would like to change this to Chapter 1 - Chapter 1 Title however. How can I achieve this? I'm using Word 2013.
1
vote
1answer
35 views

Should I write “what do the data show” or “what does the data show”? [closed]

I wonder what the proper way of writing this question is: What do the data show? What does the data show?
1
vote
5answers
180 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 ...
2
votes
0answers
40 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 ...
1
vote
3answers
87 views

Technical writer degree with an English BA?

I'm desperately trying to get out of my dead end Federal job. I have a BA in English and a love of a lot of different topics, including several science fields. I would have Majored in science if I ...
2
votes
2answers
71 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
2answers
35 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 ...
1
vote
3answers
103 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 ...
3
votes
2answers
57 views

What's the common practice for warranty chapters in technical manuals?

I'm working on a technical manual project for industrial machines and the original documents have some warranty warnings and statements at the beginning. We decided to keep them on the new documents ...
3
votes
2answers
25k 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 ...
1
vote
1answer
56 views

Order of names in title

I and two other students are writing a proposal to a corporation to donate some equipment to the Electrical Engineering department at my school. When I put our names under the title of the proposal, ...
4
votes
1answer
59 views

Writing a PhD thesis. Question about (an informal) introduction

I am preparing scientific thesis for the degree of PhD. It is a mathematical thesis. It is usually very difficult to tell your colleagues and friends what are the things you exactly work on with ...
2
votes
3answers
80 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 ...
16
votes
7answers
951 views

Best practices for maintaining documented code examples?

A good SDK (software development kit) includes plenty of well-documented examples. It also includes good tutorials and developer guides, which introduce concepts in logical progressions, typically ...
2
votes
1answer
47 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 ...
1
vote
4answers
155 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 ...
12
votes
7answers
2k views

Technical Writing Software

I'm interested in newer software/software stack to use in writing technical papers. For the longest time I have been use LaTeX to handle this but in looking at getting longer pieces published, such as ...
3
votes
1answer
54 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. ...
2
votes
3answers
115 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
1answer
110 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 ...
4
votes
1answer
400 views

in English, is it necessary to capitalize after a colon?

I've seen that each language has its own rules when using the colon. In Spanish, it's not needed to capitalize: Los elementos incluyen: secado, lavado, etc. In French is the same, and even they put ...
5
votes
6answers
904 views

Overusing “the” and “I”

I'm not a native English speaker, and I find that my English writing contains too many definite article "the" when writing scientific reports, and too many "I" when writing in informal settings (like ...
1
vote
1answer
182 views

How much detail is considered enough for literature review of a research paper

I and a few of my friends are conducting a small research project to determine the prevalence of hypertension, where we live. I was hoping I could get an opinion on how to write our literature ...
4
votes
4answers
2k views

What would sections of a book that are larger than a chapter be called?

I'm writing a technical book, and I want to split my book up into about 3 to 6 very broad sections, each of which would have several chapters in it. Is there a standard name for these broad pieces ...
4
votes
3answers
129 views

Software for keeping track of book edits?

So I'm writing a new edition of an old textbook, and I need some way of keeping track of what needs to be done, and what I have done. I could use paper - but I tend to lose that. Or even a plain text ...
8
votes
3answers
585 views

In end user documentation, should screenshots come before or after the text that references them?

The end user documentation I'm writing makes use of screenshots (and partial screenshots) to show the user what I'm referring to in procedural instructions for or conceptual explanations of the ...
1
vote
2answers
73 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 ...
3
votes
2answers
166 views

What is the average cost of software for DITA authoring?

I'm looking to buy some software for technical document authoring with DITA. The tech writing group will have at least 5-10 users, writing 100-pages long documents for several products in various ...
2
votes
3answers
166 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 ...
1
vote
1answer
39 views

How do I build a better blog website? [closed]

I've spent the last few days building a website that I want to use a showcase for my written work, and as a personal blog. What fundamental changes should I make to improve a viewer's experience? The ...
1
vote
1answer
115 views

Copyright of examples used in books?

I'm getting into non-fiction technical writing (a blog, but potentially ebook or otherwise). Often the best technical advice come from dissecting and synthesising good and bad examples from the ...
8
votes
5answers
2k views

Demo data in screenshots! What are the best practice?

My question is related to best practices of making screenshots for end-user documentation. Particularly, is there universal information for filling in forms in the software and after that making ...
-2
votes
1answer
78 views

How to write “number of cups per user” for short using symbols?

I want to insert a text segment in a figure in my conference paper. Like "number of cups per user", can I use #cups/user ? I think "cups/user" means an average value, right? What I need is a X-Y ...
10
votes
6answers
1k views

Ways to improve your writing skills

As a CS major I've learned that knowing how to write is critically important, but, I'm not really sure how to improve my writing skills. I'm currently trying to write a tech blog in English, but, ...
1
vote
1answer
116 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
2answers
87 views

Are there books to improve the style?

I've opened a question in another section: http://meta.programmers.stackexchange.com/questions/6911/is-this-question-possible-in-this-section The question is pretty unclear but for me is really hard ...
2
votes
2answers
697 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 ...
5
votes
3answers
180 views

How to leverage social proof?

How can one use social proof as an argument without sounding like "just because everybody is doing it so should you"?. My problem is trying to demonstrate with social proof that trendy ...
3
votes
3answers
328 views

Best way to write an article professionally

Is there any widely accepted step by step method for writing a creative article in a professional manner. I want to improve my English writing skills in relation to creative article writing. I read ...
8
votes
3answers
180 views

Good tools for writing (game) manuals and sourcebooks

As I had asked in another part of Stackexchange (didn't know about this part until some comments there) I'm writing manuals (mostly for computer games, but in addition to this also for tabletop games, ...