Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Posts tagged technical-writing

3 child tags

This tag doesn't have any usage information yet.

This tag doesn't have a detailed wiki yet.

66%
+2 −0
Q&A Sphinx: API documentation: How to turn off creating links to Parameter/Argument link creation

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....

0 answers  ·  posted 1y ago by CodeFarmer‭  ·  last activity 3d ago by Mithical‭

77%
+5 −0
Q&A Technical Writer Skill Set

As technology and industry demands evolve, what tools/skills should one focus on learning/improving as a technical writer?

2 answers  ·  posted 3y ago by yashikaissrani‭  ·  last activity 14d ago by ArtOfCode‭

50%
+0 −0
Q&A singular or plural for index entries

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...

2 answers  ·  posted 11y ago by jochen‭  ·  last activity 2mo ago by Herem1956‭

60%
+1 −0
Q&A Should I use contractions in a technical tutorial?

In a technical tutorial which fits better: In this tutorial you'll learn or In this tutorial you will learn or in general does it make no difference?

4 answers  ·  posted 8y ago by learnAndImprove‭  ·  last activity 3mo ago by Mithical‭

80%
+6 −0
Q&A HTML tags versus CSS classes: is one preferred over the other for the same styling?

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...

2 answers  ·  posted 2y ago by Monica Cellio‭  ·  last activity 2y ago by Canina‭

71%
+3 −0
Q&A For HTML documentation sets, are there meaningful guidelines for topic length?

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 --...

2 answers  ·  posted 5y ago by Monica Cellio‭  ·  last activity 2y ago by Mark Baker‭

75%
+4 −0
Q&A What are the benefits of including complete working code samples in documentation

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...

4 answers  ·  posted 6y ago by Lefty G Balogh‭  ·  last activity 2y ago by Monica Cellio‭

77%
+5 −0
Q&A 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...

3 answers  ·  posted 9y ago by Monica Cellio‭  ·  edited 2y ago by Monica Cellio‭

50%
+0 −0
Q&A How do I write a report analyzing a system's weaknesses and how to address them?

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...

2 answers  ·  posted 6y ago by user40‭  ·  edited 3y ago by Canina‭

81%
+7 −0
Q&A mice don't tap and tablet-users don't click: what word can I use for all audiences instead?

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...

4 answers  ·  posted 4y ago by Monica Cellio‭  ·  edited 3y ago by Canina‭

71%
+3 −0
Q&A Does DRY (Don't Repeat Yourself) Apply to Documentation?

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 ...

3 answers  ·  posted 6y ago by Scribblemacher‭  ·  last activity 3y ago by Lundin‭

66%
+2 −0
Q&A Linking documentation to Git commit comments

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...

1 answer  ·  posted 6y ago by Gypsy Spellweaver‭  ·  edited 3y ago by Monica Cellio‭

75%
+4 −0
Q&A 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 exam...

1 answer  ·  posted 9y ago by Stefan Piskorski‭  ·  edited 3y ago by Monica Cellio‭

71%
+3 −0
Q&A Syntax summaries use brackets for optional elements; how do I represent literal brackets in a way readers will understand?

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]...

4 answers  ·  posted 3y ago by Monica Cellio‭  ·  last activity 3y ago by Derek Elkins‭

50%
+0 −0
Q&A Adding tags to documentation built in Flare?

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...

0 answers  ·  posted 5y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

60%
+1 −0
Q&A How can we make images with (necessary) text more translatable mechanically?

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...

1 answer  ·  posted 5y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

77%
+5 −0
Q&A Is there any benefit when writing out instructions to split it up into lots of little paragraphs, or is it better to leave it in one paragraph?

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...

3 answers  ·  posted 3y ago by Mithical‭  ·  last activity 3y ago by Mark Baker‭

66%
+2 −0
Q&A How can we format code examples so that they work on a range of devices?

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...

1 answer  ·  posted 3y ago by Monica Cellio‭  ·  last activity 3y ago by manassehkatz‭

66%
+2 −0
Q&A 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 sente...

4 answers  ·  posted 9y ago by Dave Jones‭  ·  edited 3y ago by Monica Cellio‭

60%
+1 −0
Q&A 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 ...

4 answers  ·  posted 12y ago by Monica Cellio‭  ·  edited 3y ago by Monica Cellio‭

84%
+9 −0
Q&A Is writing policy pages in a lighthearted manner harmful in any way?

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...

2 answers  ·  posted 3y ago by Mithical‭  ·  last activity 3y ago by Mark Baker‭

75%
+4 −0
Q&A 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 answers  ·  posted 9y ago by john_doe‭  ·  last activity 3y ago by Secespitus‭

66%
+2 −0
Q&A 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 or conceptual explanations of the softwar...

2 answers  ·  posted 10y ago by Matthew Rodatus‭  ·  last activity 4y ago by Monica Cellio‭

66%
+2 −0
Q&A Documenting framework features and descriptions

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...

3 answers  ·  posted 4y ago by Grim‭  ·  last activity 4y ago by Monica Cellio‭

71%
+3 −0
Q&A What is Documentation Design that I haven't already done?

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...

1 answer  ·  posted 4y ago by user2263986‭  ·  last activity 4y ago by Mark Baker‭

71%
+3 −0
Meta Search page should link to advanced search options help page

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 ...

0 answers  ·  posted 4y ago by Stevoisiak‭  ·  edited 4y ago by Stevoisiak‭

71%
+3 −0
Q&A Computer science academic conference paper using "randvar" instead of "random variable"

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...

1 answer  ·  posted 4y ago by user118967‭  ·  last activity 4y ago by Amadeus‭

77%
+5 −0
Q&A The excessive use of 'and'

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...

5 answers  ·  posted 4y ago by Chagat Nahn‭  ·  last activity 4y ago by Mark Baker‭

71%
+3 −0
Q&A How I should handle gender-neutral pronouns in technical writing?

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...

3 answers  ·  posted 8y ago by Manmohan Singh‭  ·  last activity 4y ago by Amadeus‭

66%
+2 −0
Q&A 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 affects someone else's part; this coul...

4 answers  ·  posted 12y ago by Monica Cellio‭  ·  last activity 4y ago by Monica Cellio‭

71%
+3 −0
Q&A What are the indentation rules for the paragraph introducing a bulleted list?

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...

0 answers  ·  posted 4y ago by Troyen‭  ·  last activity 4y ago by System‭

66%
+2 −0
Q&A Personal or impersonal in a technical resume

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...

2 answers  ·  posted 5y ago by Liquid‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A What's the least distracting method to inform editors I'm a woman?

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...

5 answers  ·  posted 6y ago by Morgan Meredith‭  ·  last activity 4y ago by System‭

66%
+2 −0
Q&A Acronyms in Technical Writing

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

4 answers  ·  posted 6y ago by Rachel‭  ·  last activity 4y ago by System‭

40%
+0 −1
Q&A How hard would it be to find writing jobs with an English degree?

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...

1 answer  ·  posted 7y ago by user22102‭  ·  last activity 4y ago by System‭

71%
+3 −0
Q&A How to move back to main section after finishing a sub-section

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...

4 answers  ·  posted 7y ago by AKC‭  ·  last activity 4y ago by System‭

71%
+3 −0
Q&A Can basic grammar rules be skipped when writing text for machine safety labels?

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...

9 answers  ·  posted 8y ago by Montag451‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A High Tech Audience

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...

2 answers  ·  posted 8y ago by rashidali‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A Should you emphasise text within quotation marks?

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...

2 answers  ·  posted 8y ago by XPMai‭  ·  last activity 4y ago by System‭

60%
+1 −0
Q&A How to work on a new software feature that affects different topics

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...

2 answers  ·  posted 8y ago by System‭  ·  last activity 4y ago by System‭

60%
+1 −0
Q&A 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 w...

1 answer  ·  posted 8y ago by Colin747‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A 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 c...

2 answers  ·  posted 8y ago by Jonas Byström‭  ·  last activity 4y ago by System‭

60%
+1 −0
Q&A 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 document...

2 answers  ·  posted 9y ago by Montag451‭  ·  last activity 4y ago by System‭

60%
+1 −0
Q&A 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 f...

4 answers  ·  posted 9y ago by Shahbaz‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A 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 gam...

1 answer  ·  posted 9y ago by Thomas E.‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A How to write to accommodate subsequent automatic translation

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...

1 answer  ·  posted 10y ago by user7610‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A Should I have an introducing paragraph in every chapter of my description?

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...

1 answer  ·  posted 10y ago by mart‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A 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 sc...

1 answer  ·  posted 10y ago by Yuliya Drygybka‭  ·  last activity 4y ago by System‭

50%
+0 −0
Q&A What is the correct word/term that needs to be before the names of the maker of the project?

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...

1 answer  ·  posted 11y ago by Belgi‭  ·  last activity 4y ago by System‭

60%
+1 −0
Q&A 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 tha...

2 answers  ·  posted 11y ago by Carl Morris‭  ·  last activity 4y ago by System‭