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
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
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 6mo ago by CodeFarmer‭

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 &lt;code&gt; tags. My question is about styling these in tables. On our referenc...

2 answers  ·  posted 1y ago by Monica Cellio‭  ·  last activity 9mo 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 4y ago by Monica Cellio‭  ·  last activity 1y 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 5y ago by Lefty G Balogh‭  ·  last activity 1y ago by Monica Cellio‭

75%
+4 −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 8y ago by Monica Cellio‭  ·  edited 1y 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 5y ago by user40‭  ·  edited 1y 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 2y ago by Monica Cellio‭  ·  edited 1y 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 5y ago by Scribblemacher‭  ·  last activity 2y 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 5y ago by Gypsy Spellweaver‭  ·  edited 2y 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 8y ago by Stefan Piskorski‭  ·  edited 2y ago by Monica Cellio‭

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 2y ago by yashikaissrani‭  ·  last activity 2y ago by Mark Baker‭

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 2y ago by Monica Cellio‭  ·  last activity 2y 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 4y ago by Monica Cellio‭  ·  edited 2y 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 4y ago by Monica Cellio‭  ·  edited 2y 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 2y ago by Mithical‭  ·  last activity 2y 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 2y ago by Monica Cellio‭  ·  last activity 2y 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 8y ago by Dave Jones‭  ·  edited 2y 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 11y ago by Monica Cellio‭  ·  edited 2y 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 2y ago by Mithical‭  ·  last activity 2y 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 8y ago by john_doe‭  ·  last activity 2y 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 9y ago by Matthew Rodatus‭  ·  last activity 2y 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 3y ago by Grim‭  ·  last activity 3y 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 3y ago by user2263986‭  ·  last activity 3y ago by Mark Baker‭

71%
+3 −0
Q&A 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 3y ago by Stevoisiak‭  ·  edited 3y 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 3y ago by user118967‭  ·  last activity 3y 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 3y ago by Chagat Nahn‭  ·  last activity 3y 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 7y ago by Manmohan Singh‭  ·  last activity 3y 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 11y ago by Monica Cellio‭  ·  last activity 3y 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 3y ago by Troyen‭  ·  last activity 3y 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 4y ago by Liquid‭  ·  last activity 3y 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 5y ago by Morgan Meredith‭  ·  last activity 3y 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 5y ago by Rachel‭  ·  last activity 3y 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 6y ago by user22102‭  ·  last activity 3y 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 6y ago by AKC‭  ·  last activity 3y 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 6y ago by Montag451‭  ·  last activity 3y 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 7y ago by rashidali‭  ·  last activity 3y 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 7y ago by XPMai‭  ·  last activity 3y 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 7y ago by Colin747‭  ·  last activity 3y 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 7y ago by System‭  ·  last activity 3y 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 7y ago by Jonas Byström‭  ·  last activity 3y 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 8y ago by Montag451‭  ·  last activity 3y 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 8y ago by Shahbaz‭  ·  last activity 3y 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 8y ago by Thomas E.‭  ·  last activity 3y 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 9y ago by user7610‭  ·  last activity 3y 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 9y ago by mart‭  ·  last activity 3y 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 9y ago by Yuliya Drygybka‭  ·  last activity 3y 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 10y ago by Belgi‭  ·  last activity 3y ago by System‭

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

1 answer  ·  posted 10y ago by jochen‭  ·  last activity 3y ago by System‭

50%
+0 −0
Q&A What is the word for the action of selecting an item by a mouse?

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

2 answers  ·  posted 10y ago by Konrad Höffner‭  ·  last activity 3y ago by System‭

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

2 answers  ·  posted 10y ago by Jewelya‭  ·  last activity 3y ago by System‭

This community is part of the Codidact network. We have other communities too — take a look!

You can also join us in chat!

Want to advertise this community? Use our templates!

Like what we're doing? Support us! Donate