Posts tagged technical-writing
As technology and industry demands evolve, what tools/skills should one focus on learning/improving as a technical writer?
For projects with API documentation generated by Sphinx, I've noticed that some project's don't include links to the Parameter/Argument types (str, file-like object, int, etc) and some projects do....
We publish documentation online using HTML. For things like fixed parameter names and other code literals, we use <code> tags. My question is about styling these in tables. On our referenc...
We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics --...
When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding l...
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...
I was asked to prepare an overview of an existing IT architechture and provide a document that consists of weaknesses analysis and suggestions on how each of the weak spots can be improved. How to...
I am documenting features on a web site. The audience is end users, who could be anywhere from seasoned Internet veterans to relatively new people who came for my site's content but aren't general...
In programming, it's usually accepted that DRY code is better code in most situations. Does this principle also apply to documentation? I'm asking about the documentation output, not necessarily ...
Using git to track modifications to the project allows contributors to include comments with each commit. If the project's guidelines, and managers' control, keeps those comments limited to a forma...
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 exam...
In our documentation of SQL functions and statements, we include a BNF-style syntax summary. As is conventional, we indicate optional elements in square brackets, like this: CREATE [IF NOT EXISTS]...
Our software documentation set (for a SQL analytics database platform) is large, because SQL and databases have many pieces. Often a single statement, function, or feature will be highly related to...
Our documentation set includes some diagrams, such as entity relationship diagrams and flowcharts, where text is integral and cannot reasonably be handled in callouts. Our documentation is translat...
I was putting together an instruction page (for setting up a game that my business created), which included a whole lot of various pointers, most of which were only a sentence or two long. These ex...
We use Madcap Flare to produce a large documentation set that contains many code examples (primarily SQL, but also C++, Java, and Python) and command-line operations. When the doc set was first pl...
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 sente...
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 ...
Recently, I threw together a draft of a policy page about promotional content, with some guidelines on what to keep in mind to avoid spamming. (Incidentally, this is for Codidact itself.) I decided...
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 ...
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 or conceptual explanations of the softwar...
We have written a custom software framework and it has grown to the point where we are ready for documentation. This documentation will be used by other developers to share knowledge. I am concerne...
I'm a contractor who has been working on a project (a developer guide website) for months with another contractor writer. We spent a lot of time: Interviewing end users Designing the deliverable...
The question search page has a short description of advanced search options, but it doesn't tell users what search operators are available. It should include a link to the advanced search options ...
I am reviewing a computer science submission to an academic conference. The authors use "randvar" instead of "random variable" (as well as "logvar" instead of "logical variable"). I am wondering i...
The word 'and' is an indispensable conjoining tool in any form and discipline of writing. Although, a repetition of the word can make a paragraph too tedious to read, and it only lengthens a senten...
I am writing API documentation for a mobile loyalty program and I am not sure which of the following is better wording: 1) When the user requests for their visit and order to be registered in thei...
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 affects someone else's part; this coul...
I'm writing a formal document for my company where it'll be shared and used by a number of teams. Unfortunately, we don't have any official standard style guide to follow, so I've attempted to be a...
In CVs or on Linkedin profiles there are often spaces dedicated to past experience. In those sections, one is supposed to describe what work he/she did and what skills he/she acquired on previous...
I have a gender-neutral name, so people often assume I'm a man. However, a portion of the writing I do is for tech companies. Because of the lack of diversity in the tech industry, many of these c...
I can't find a standard, is the most common use to have the abbreviation followed by the defintion? Example NATO: North Atlantic Treaty Organization
I would love to work as a technical writer, copy editor, journalist, or whatever--as long as it's related to writing. I would especially love to freelance and complete contracts every day. So, I've...
I am writing a paper but I don't know how to move back to the main section after I'm done writing a sub-section, like this: 1.1 Main section 1.1.1 subsection 1 1.1.2 subsection 2 As I write long...
First of all I'm completely against this idea but a few people who contribute to the technical documentation project constantly suggest that to attain a short, quick, economic, comprehensive messag...
I have to write a simple introduction on the topic HTTP and its audience will be high tech. I am having a bit of problem in how to describe it in high tech audience? Can any one would suggest me h...
e.g. Bold: Click "Setting" then click "Options". Italic: Click "Setting" then click "Options". Or even underline? Or none quotation marks? Click Setting then click Options. Wh...
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 w...
We're working on a software manual with several chapters and topics and, so far, these are mostly self-contained. This means we have a dedicated chapter for "connectivity" and do not mention connec...
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 c...
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 document...
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 f...
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 gam...
The texts I am writing will be translated by people who are not experts in the topic and in some cases by a machine with next to none human editing afterwards. What strategies should I employ to e...
I'm about to write a technical description for an industrial process. The description will follow logical blocks, or blocks from the PFD of the process. This a sales document aimed at (mostly) engi...
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 sc...
I am doing a project with one other person, we have finished the project and we are working on a cover page. We are not sure what to write out before our names, we have thought of a couple of opti...
I am in the final stages of writing a book and currently I am preparing the index. Are there any rules whether index entries should be listed in singular or plural? Currently I have Markov chains...
I am writing a tutorial on how to use a specific web application and I don't know which verbs to use. Shall I use "click" for buttons? But what if the user doesn't use a mouse? Contrary to "normal"...
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 t...
