Writing Stack Exchange
Writing Stack Exchange

Questions tagged [software-documentation]

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

For questions that apply to all technical writing and not just software, use . If you have a spare tag slot, go ahead and tag software-doc questions with technical-writing too, so that people searching the broader tag will find them.

For questions about API documentation (a type of software doc), use .

If applicable, also tag with the specific type of documentation, like , , , or (this is not necessarily a complete list).

Software documentation often includes .

52 questions
37
votes
7 answers

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 how to use something. (I'm specifically talking…
Sharon M
  • 738
  • 5
  • 11
25
votes
9 answers

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. Product documentation will surely include that…
Mark Ireland
22
votes
7 answers

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 showing only the relevant excerpts from the sample…
Monica Cellio
  • 21,489
  • 3
  • 68
  • 110
17
votes
4 answers

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 documentation, but when. And what to add. Doxygen…
Summer
  • 4,481
  • 2
  • 22
  • 60
17
votes
3 answers

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 code) and is passed on to a more objective audience…
Jason Fox
  • 477
  • 2
  • 13
13
votes
8 answers

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 product might be "user". How do I indicate to the new…
MechtEngineer
  • 257
  • 3
  • 10
12
votes
3 answers

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 is expected that additional services will be added…
Jason Fox
  • 477
  • 2
  • 13
11
votes
2 answers

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 granular pages? Which organization should I choose to…
user23425
11
votes
2 answers

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 capitalize them), and also often double as the names of…
interfect
  • 213
  • 1
  • 4
10
votes
4 answers

Should user manuals be organized by feature or process?

We have developed a software package and need to write a user manual. I'm trying to determine if the manual should be approached from the perspective of "process" (i.e. accomplishing specific business tasks) or "features" (i.e. the different parts…
RHarris
  • 203
  • 1
  • 3
10
votes
5 answers

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 language, a "hello world" style sample API client…
Lefty G Balogh
  • 554
  • 5
  • 8
10
votes
4 answers

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 systems, several development stages, several…
Helmar
  • 626
  • 9
  • 18
10
votes
3 answers

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 arguments at all (just foo). I'm struggling with…
Nick Volynkin
  • 355
  • 2
  • 11
10
votes
10 answers

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 a Database", ...) Descriptive form: (e.g. "Cluster…
Adam Matan
  • 283
  • 3
  • 8
10
votes
2 answers

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 examples of good code/ database documentation that have…
Stefan Piskorski
  • 115
  • 1
  • 6
1
2 3 4