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

learn more… | top users | synonyms

1
vote
3answers
44 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 ...
0
votes
0answers
50 views

Any other ways to get paid for web content writing, not by words? [on hold]

Been working as a freelance writer for over 2 yrs now. Worked with 2 webs, still work with one of them. Paid by words per article, but some of my creative works deserve more. So is there any other ...
3
votes
2answers
45 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
21k 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
53 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, ...
3
votes
1answer
44 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
58 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
914 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
25 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
131 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
49 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
93 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
58 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
391 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
713 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
97 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
125 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
524 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
61 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
112 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
133 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
38 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
87 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
1k 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
73 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 ...
9
votes
6answers
955 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
87 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
84 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
426 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
179 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
283 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
166 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, ...
8
votes
2answers
364 views

Good Examples of and Practices in Code Documentation

I noted in this question: What is the best way to learn technical writing? ...that a rated method to learn how to write technical documents is to imbibe good examples. Can you recommend any ...
4
votes
3answers
422 views

Do Decimals Bounded Between 0 and 1 (inclusive) Need a Leading Zero?

For a variable bounded between 0 and 1 inclusive, [0,1], should I use a leading zero when quoting a number? E.g. the probability of rain is 0.5 or .5 (I realize this should technically be 50%, but I ...
5
votes
2answers
197 views

How should I document a database schema?

I am going to be writing some user-facing documentation for a database that visitors can query. That is, the people writing queries are not the ones who created the database; they can come in, look ...
4
votes
1answer
94 views

How do I approach rewriting an entire user guide in an agile environment?

I'm tasked with rewriting an entire user guide that hasn't been updated for years at a company and I am the only technical writer on the team. Only release notes were sent out all these years. The ...
2
votes
3answers
508 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
2answers
77 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 ...
3
votes
4answers
118 views

Is this title suitable for a chapter section?

Suppose I am writing a chapter about some deep technical subject (say, for instance, "boolean variables"). This theme is riddled with idiosyncrasies and misunderstandings, so I would like to present ...
8
votes
3answers
183 views

How do you track dependencies for your co-authors?

I and one or more co-authors, sometimes geographically distributed, are working on a set of related documents. Sometimes I will make a change in my part that has effects on someone else's part; this ...
0
votes
1answer
32 views

Write a presentation of a dissertation [closed]

we have made a dissertation about a type of insect called Pine Processionary Moth. we have upplied some statistical methods on it: data analysis and cluster analysis!! we have almost finished, but i ...
6
votes
2answers
282 views

Best Tool to Create User Guides

We are planning to create a user guide for internal use only. It's 150-page document in Word for a self-developed SW tool. The user guide will require constant update. No translation is needed. We ...
4
votes
3answers
268 views

Online technical writing classes

anyone aware of or can recommend online training courses for technical writers to improve your technical writing skills? I'm looking for courses that provide video or audio lectures, and teachers ...
5
votes
4answers
570 views

How can I write better code-based reference documentation for programming interfaces?

Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc). All I have to do is add some comments explaining what a class or method does and what ...
4
votes
3answers
325 views

When is a screen shot really useful in training documentation?

Software products evolve more rapidly each day. Technical documentation for those products must also follow their evolution. One of the biggest challenges is to maintain screen shots when the ...
0
votes
2answers
266 views

Looking for sites that describe minimalist writing for technical content

I'm looking for a site or sites that describe minimalist writing (http://en.wikipedia.org/wiki/Minimalism_(technical_communication)). The Wikipedia article is so minimalist it doesn't provide such ...
2
votes
4answers
1k 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 ...
1
vote
1answer
38 views

Author order and grouping on technical document

This question pertains to author/contributor order and grouping on a technical document. I performed tests on some equipment and had two other people directly involved. My boss and his boss need to ...