Questions tagged [software-documentation]

Technical-writing questions that are specific to documenting software. See further guidance in the wiki.

Filter by
Sorted by
Tagged with
36
votes
7answers
5k views

Should software product release notes be in marketing voice or technical voice? (software documentation)

Typically, the voice of marketing content doesn't match the voice of technical content -- marketing is trying to persuade you that you need something; technical writing is generally instructing you ...
24
votes
9answers
41 views

Should beta functionality be mentioned in a training manual?

I write training manuals for a software product. When that product is next released one of the tools in it will be marked "in beta". i.e. that functionality is is included only as a technical preview. ...
22
votes
7answers
2k 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 ...
17
votes
3answers
2k views

How should I document a product release with an inherently flawed design?

The deadline is looming and someone realizes the product can't be shipped without documentation. Once the product leaves the remit of the software engineers (who obviously only ever write wonderful ...
14
votes
4answers
4k views

Where do I start with C++ documentation?

I am new to programming and am entirely self-taught. I have reached a point in my writing where a solid grasp of documentation standards would be greatly beneficial. My question is not how to add ...
12
votes
8answers
48 views

What are standard techniques that indicate to the documentation reader that they are to substitute their own appropriate text (e.g. username, domain)?

When reading manuals or guides, I can easily get confused between what is meant to be example text, and what is actually meant to be used. For example, sometimes the username to login to use a ...
11
votes
2answers
973 views

Structure for software documentation: long vs short pages

For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more ...
11
votes
3answers
541 views

How to effectively document a product composed of complex microservices?

I have a highly flexible software product consisting of a series of loosely coupled microservices. Each component is effective at a single job, but may be dependent on inputs from other services. It ...
10
votes
2answers
390 views

Starting a sentence with the name of a program or command-line tool: capitalization?

Say you want to talk about a piece of command-line software, like make or bash or the cp command. These commands are all lower-case, and case-sensitive (i.e. won't work on the computer if you ...
10
votes
3answers
247 views

Documenting the no-args call of a command line program

I am writing the built-in help for a command line program. The exact name is irrelevant, so let's use foo as a placeholder. This utility can be called with some arguments (like foo -v) or without any ...
10
votes
2answers
3k 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 ...
10
votes
4answers
104 views

How to Document Systems with Different Versions?

Scenario I need to create and maintain a user documentation for a system of which there are different instances in use by different target groups. There are several levels of integration with other ...
9
votes
5answers
82 views

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 ...
9
votes
2answers
2k 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 ...
9
votes
1answer
76 views

Have there been any studies indicating which software documentation practices save the most time during onboarding?

It's generally conceded that at least some documentation saves people time when "onboarding" to a new project. With that said, have there ever been any rigorous studies on how helpful various kinds of ...
8
votes
4answers
2k 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 ...
8
votes
4answers
58 views

Is it better to repeat steps listed elsewhere in a manual, or to refer the reader to where the steps are listed elsewhere in the manual?

We have a tool that we cannot replace that does not support single sourcing. As a result, with instructions that involve the same node, we either repeat the same dozen steps over and over, or refer ...
8
votes
5answers
167 views

What are some standards in naming a software/hardware version?

I am wondering if how we name a version of a spacecraft differs from how we name a version of a software. For software, I usually see things like "2.0.32.32" or something like that and sometimes they ...
8
votes
2answers
47 views

What strategies are there to document data lineage and keep it updated with a minimum amount of maintenance?

Quickly communicating data lineage to other stakeholders in our organization has become increasingly difficult as we scale. What are effective strategies to address this and keep it maintained? An ...
7
votes
8answers
2k views

Verb tense for technical document titles

I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names. My ideas are: Continuous (-ing) form: (e.g. "Creating a Cluster", "Creating ...
7
votes
5answers
158 views

Alternatives better to the binary “0b…” format?

In our documentation, we write binary numbers like this: 1010 But we write hexadecimal numbers like this: 0xABAB Now, according to the GCC compiler conventions: Numbers are normally written in ...
7
votes
3answers
57 views

How to include external references when writing internal documentation?

In the IT industry, we often write a lot of technical documentation meant for internal use only. Those documents are often stored in an internal wiki and accessed when the need arises. The content ...
7
votes
2answers
71 views

Strategies for writing software design documents

I'm a self-taught programmer which means I started writing software by sitting down at an IDE and hammering out some code. When my decisions ultimately coded me into a corner I would refactor and ...
7
votes
3answers
776 views

Methods for writing a code review

I currently spend a good deal of time over at Code Review and I would love to improve the quality of the reviews I write. Can you give me any insight into the structure or approach you use when ...
7
votes
2answers
82 views

How do I maintain effective documentation for different audiences while avoiding duplication?

I need to maintain documentation of the same system for different audiences. How do I avoid duplication while still being effective? I have a publicly-available API, and I also have internal ...
7
votes
1answer
617 views

Format keyboard keys in documents

I'm writing a guide to give step-by-step instructions to complete some tasks on the computer. At some points, I need to indicate pressing keys on the keyboard; how may I format the letter/symbol to ...
7
votes
2answers
165 views

Standards for representing user interaction

I am responsible for developing internal IT documentation but have only begun my scratching the surface on technical documentation. Is there a standard or best practice for the following: Example 1:...
6
votes
5answers
42 views

Bridging the gap between colloquial usage and technical meaning of terms

Frequently, at least in the software world, it seems that terms get assigned a meaning over time that is more general than the original definition. REST is a good example of this. While REST refers ...
6
votes
1answer
2k views

Is there a style / terminology guide for Android OS application documentation?

This relates to my earlier question: Habits and routines for my first tech writing job I will be involved with writing documentation for an Android OS business application. Is there an Android style ...
5
votes
2answers
22 views

Are UML component diagrams helpful to non-technical users?

Are high-level UML-style component diagrams helpful to non-technical people? How likely would they be to understand something like that and, if so, how interesting/useful is that likely to be for ...
5
votes
2answers
77 views

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 -- ...
5
votes
4answers
426 views

How can I consistently distinguish among tables, fields, and records in a database?

I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows). I spend a lot of time discussing tables and ...
5
votes
2answers
81 views

Documenting software requirements

As a self-taught developer the only requirement documents I've ever been privileged to read are those of hackerrank and the sort. However the more and more I create my own increasingly complex ...
5
votes
1answer
33 views

Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods?

At this point, many languages have some "standard" format for writing documentation for individual methods. This includes, for example, Java Annotation and Microsoft's XML Documentation for .NET ...
5
votes
1answer
98 views

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 a ...
4
votes
3answers
166 views

Can I use LaTeX in a fictional code-weaving?

I'm working on a magic system that works with weaving types of power. The most commonly used power source is a magical code. I'm trying to base this code off of latex. LaTeX is a math code that is ...
3
votes
1answer
90 views

Is markdown a good choice for large-scale, web-based software developer documentation?

"Markdown" has become very popular for people creating developer documentation due to how easy it is to learn compared to most alternatives. Unfortunately there are dozens of "flavors" of markdown and ...
3
votes
2answers
69 views

Should the documentation of a known issue change dependent on the stability of a product release?

I am writing the release documentation for a software product and a design flaw has been discovered after the code has been frozen. Does the documentation describing this issue change if the product ...
3
votes
2answers
30 views

Our team needs to automate many routine tasks. Can we use a single tool or do we need to use multiple ones?

Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using Sphinx, reStructuredText, Adobe Illustrator, and Visio. Specific things we need ...
3
votes
1answer
23 views

What advantages are there to having a project-specific website for documentation?

As a software engineer I often interact with documentation for software projects across the Internet, in particular on GitHub which provides methods for documenting your project. Anecdotally, it ...
2
votes
3answers
8 views

Terminology question - “if-else” or “if/else”?

Are they "if-else statements" or are they "if/else statements"? I'm partial to the latter, but I can see the logic of the former - both "if" and "else" are acting as a unit modifier for the noun "...
1
vote
2answers
157 views

How can I get a technical writing job for software apps without a degree? [duplicate]

I have no degree and I cannot afford to have one, however, I would really love to get into technical writing because I love writing and I am interested in web and software development. Right now, I am ...
1
vote
2answers
60 views

What is the status of Sandcastle and are there alternatives?

Wikipedia currently lists the Development Status of the Sandcastle documentation generation software as "Stalled," citing the lack of recent releases. (There's actually contradictory information on ...