Posts tagged software-documentation
Subtag of technical-writing
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 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 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...
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...
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...
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 ...
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 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", "Creat...
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 conten...
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 th...
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...
Often while writing a software requirement/change-request documentation, I need to include the quoted requirements descriptively, the impacted modules, the changes provided both in UI and in logic....
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 wri...
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 r...
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. I...
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...
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 d...
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 capit...
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...
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...
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 a...
Good time of the day, community! Hope, that my post won't irritate too much, but rather will be helpful for someone in future. I already made some progress myself (I mean some raw unfinished vers...
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 ...
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 gr...
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...
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 "s...
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 refe...
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 La...
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 n...
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...
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? A...
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 produc...
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...
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 ...
