https://writing.codidact.com/categories/1/tags/337.rssNew Posts Tagged 'documentation' - WritingWriting - Codidact2021-02-09T15:28:12Zhttps://writing.codidact.com/posts/280710What are some ways to encourage team members to contribute and maintain a centralized wiki?Sigmahttps://writing.codidact.com/users/82632021-02-08T13:35:34Z2021-02-09T15:28:12Z<p>I joined my current company and department a few years ago. We had some documentation for processes but most people had been around for a long time and never needed it, so it was very sparse.</p...https://writing.codidact.com/posts/35035Adding tags to documentation built in Flare?Monica Celliohttps://writing.codidact.com/users/80462019-03-25T20:58:51Z2020-11-17T04:02:07Z<p>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...https://writing.codidact.com/posts/38525Documenting framework features and descriptionsGrimhttps://writing.codidact.com/users/78822019-09-24T17:31:31Z2020-02-27T04:13:36Z<p>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 conce...https://writing.codidact.com/posts/1905Verb tense for technical document titlesAdam Matanhttps://writing.codidact.com/users/1902011-02-10T13:34:08Z2019-12-13T11:59:55Z<p>I'm writing a technical manual about creating database systems, and wondered what is the best verb tense for title names.</p>
<p>My ideas are:</p>
<ul>
<li>Continuous (<code>-ing</code>) form:...https://writing.codidact.com/posts/34636How to include external references when writing internal documentation?Liquidhttps://writing.codidact.com/users/80572019-03-15T11:26:16Z2019-12-13T11:56:50Z<p>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. </p>
<p>...https://writing.codidact.com/posts/37074What are some standards in naming a software/hardware version?blackbirdhttps://writing.codidact.com/users/74992019-07-04T23:33:55Z2019-12-13T09:04:47Z<p>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...https://writing.codidact.com/posts/26048Should software product release notes be in marketing voice or technical voice? (software documentation)Sharon Mhttps://writing.codidact.com/users/59252018-02-13T18:07:57Z2019-12-12T23:01:20Z<p>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 ...https://writing.codidact.com/posts/38199How to eliminate standoff between "Lengthy" vs "Concision"?Karan Desaihttps://writing.codidact.com/users/49182019-09-02T12:52:24Z2019-12-08T18:46:46Z<p>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 log...https://writing.codidact.com/posts/34879What is special in API documentation compared to general technical writing?Gergelyhttps://writing.codidact.com/users/73232019-03-21T10:55:54Z2019-12-08T18:46:45Z<p>The title says it all: what is special in Application Programming Interface documentation compared to general technical writing? What aspects should I take care of?</p>
https://writing.codidact.com/posts/33791Methods for writing a code reviewAGirlHasNoNamehttps://writing.codidact.com/users/63122019-02-26T03:46:20Z2019-12-08T18:46:45Z<p>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 ...https://writing.codidact.com/posts/33725Strategies for writing software design documentsAGirlHasNoNamehttps://writing.codidact.com/users/63122019-02-24T04:44:14Z2019-12-08T18:46:45Z<p>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 an...https://writing.codidact.com/posts/26321How to effectively document a product composed of complex microservices?Jason Foxhttps://writing.codidact.com/users/59352018-02-11T13:22:07Z2019-12-08T18:46:44Z<p>I have a <strong>highly flexible</strong> software product consisting of a series of loosely coupled <a href="https://en.wikipedia.org/wiki/Microservices" rel="nofollow noreferrer">microservices...https://writing.codidact.com/posts/30668How can I get a technical writing job for software apps without a degree?Camilla S.https://writing.codidact.com/users/66682018-09-12T04:52:26Z2019-12-08T18:46:44Z<p>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...https://writing.codidact.com/posts/28364Where do I start with C++ documentation?AGirlHasNoNamehttps://writing.codidact.com/users/63122018-05-17T22:57:02Z2019-12-08T18:46:44Z<p>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 ad...https://writing.codidact.com/posts/17552Starting a sentence with the name of a program or command-line tool: capitalization?interfecthttps://writing.codidact.com/users/42952016-06-18T02:37:02Z2019-12-08T18:46:43Z<p>Say you want to talk about a piece of command-line software, like <code>make</code> or <code>bash</code> or the <code>cp</code> command. These commands are all lower-case, and case-sensitive (i....https://writing.codidact.com/posts/19370How can I publish package overviews (Java) or namespace overviews (C++) using Doxygen?Monica Celliohttps://writing.codidact.com/users/80462016-12-20T01:22:57Z2019-12-08T18:46:43Z<p>We use <a href="http://www.doxygen.nl/" rel="nofollow noreferrer">doxygen</a> to generate API (reference) documentation for our code. We have a small Java API and a large C++ API. The usual to...https://writing.codidact.com/posts/15049Format keyboard keys in documentsOxwivihttps://writing.codidact.com/users/9632015-10-22T11:05:45Z2019-12-08T18:46:42Z<p>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...https://writing.codidact.com/posts/11297Tools for multiple creators/writers documentation without cloudsThomas E.https://writing.codidact.com/users/26922014-09-30T08:01:35Z2019-12-08T18:46:41Z<p>In many companies I've seen it that more than 1 person are writing at the same documentation (be it user manual or technical documentation) for a computer application.</p>
<p>What I have seen i...https://writing.codidact.com/posts/9984How can I write better code-based reference documentation for programming interfaces?Monica Celliohttps://writing.codidact.com/users/80462014-03-13T01:37:28Z2019-12-08T18:46:41Z<p>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 w...https://writing.codidact.com/posts/8276API reference doc: best practices for describing opaque parameters?Monica Celliohttps://writing.codidact.com/users/80462013-07-24T02:20:11Z2019-12-08T18:46:40Z<p>The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typica...https://writing.codidact.com/posts/7385How can I consistently distinguish among tables, fields, and records in a database?Abehttps://writing.codidact.com/users/19182013-03-26T19:42:47Z2019-12-08T18:46:39Z<p>I am describing a database for a scientific publication. The database has many tables, and each table has fields (spreadsheet columns) and records (rows).</p>
<p>I spend a lot of time discussin...https://writing.codidact.com/posts/37888Technical specification for webservice (developers-oriented) - examples, methods & instrumentsAnton FromButovohttps://writing.codidact.com/users/77732019-08-19T05:12:16Z2019-12-08T12:44:59Z<p>Good time of the day, community!</p>
<p>Hope, that my post won't irritate too much, but rather will be helpful for someone in future.</p>
<p>I already made some progress myself (I mean some ra...https://writing.codidact.com/posts/36925Preferred word for "preferred", "target", "chosen" in end user support documentationPierce Devolhttps://writing.codidact.com/users/76242019-06-26T17:44:29Z2019-12-08T12:18:31Z<p>I'm having trouble finding and sticking to one word to indicate whatever value the user intends to use with my instructions. </p>
<p>For example:</p>
<blockquote>
<p>Select your preferred pr...https://writing.codidact.com/posts/27537Can I use LaTeX in a fictional code-weaving?FoxElementalhttps://writing.codidact.com/users/61852018-04-16T17:37:21Z2019-12-08T08:32:44Z<p>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 <a href="/questions/tagged/latex"...https://writing.codidact.com/posts/26808Structure for software documentation: long vs short pagesSystemhttps://writing.codidact.com/users/-12018-03-09T09:14:57Z2019-12-08T08:15:25Z<p>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...https://writing.codidact.com/posts/26385Limitations of automatic documentationTimtechhttps://writing.codidact.com/users/31122018-01-24T06:45:00Z2019-12-08T08:04:23Z<p>As technology advances and workflows are streamlined, some have turned to automated tools such as <a href="http://en.wikipedia.org/wiki/Doxygen" rel="noreferrer">Doxygen</a>, <a href="https://en...https://writing.codidact.com/posts/26375Alternatives better to the binary "0b..." format?Yoelhttps://writing.codidact.com/users/59622018-01-31T13:17:40Z2019-12-08T08:04:11Z<p>In our documentation, we write binary numbers like this:
<strong>1010</strong></p>
<p>But we write hexadecimal numbers like this:
<strong>0xABAB</strong> </p>
<p>Now, according to the GCC comp...https://writing.codidact.com/posts/26371Terminology question - "if-else" or "if/else"?Yoelhttps://writing.codidact.com/users/59622018-01-31T13:04:00Z2019-12-08T08:04:03Z<p>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...https://writing.codidact.com/posts/26365Bridging the gap between colloquial usage and technical meaning of termsthesquaregroothttps://writing.codidact.com/users/59362018-01-26T16:18:45Z2019-12-08T08:03:59Z<p>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. <a href="https://en.wikipedia.org/wiki/Repres...https://writing.codidact.com/posts/26316Are there valid reasons to write Java Annotation (or .NET XML Documentation) for private methods?EJoshuaS - Reinstate Monicahttps://writing.codidact.com/users/59692018-01-30T17:33:46Z2019-12-08T08:02:42Z<p>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...https://writing.codidact.com/posts/26303Our team needs to automate many routine tasks. Can we use a single tool or do we need to use multiple ones?David Vogelhttps://writing.codidact.com/users/59742018-01-28T16:20:42Z2019-12-08T08:02:28Z<p>Our tech comm team has a wide variety of time-consuming, repetitive tasks they we need to automate. We are mainly using <a href="http://www.sphinx-doc.org/en/stable/index.html" rel="nofollow nor...https://writing.codidact.com/posts/26298Is 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?Lefty G Baloghhttps://writing.codidact.com/users/59712018-02-04T13:45:41Z2019-12-08T08:02:26Z<p>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 re...https://writing.codidact.com/posts/26284What strategies are there to document data lineage and keep it updated with a minimum amount of maintenance?David Vogelhttps://writing.codidact.com/users/59742018-01-24T00:06:40Z2019-12-08T08:02:04Z<p>Quickly communicating <a href="https://en.wikipedia.org/wiki/Data_lineage" rel="noreferrer">data lineage</a> to other stakeholders in our organization has become increasingly difficult as we sca...https://writing.codidact.com/posts/26091Should the documentation of a known issue change dependent on the stability of a product release?Jason Foxhttps://writing.codidact.com/users/59352018-02-14T14:20:50Z2019-12-08T07:57:38Z<p>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 pro...https://writing.codidact.com/posts/26083How should I document a product release with an inherently flawed design?Jason Foxhttps://writing.codidact.com/users/59352018-02-14T12:36:28Z2019-12-08T07:57:31Z<p>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 wonder...https://writing.codidact.com/posts/20622Documenting the no-args call of a command line programNick Volynkinhttps://writing.codidact.com/users/49322017-03-01T10:07:31Z2019-12-08T06:11:32Z<p>I am writing the built-in help for a command line program. The exact name is irrelevant, so let's use <code>foo</code> as a placeholder.</p>
<p>This utility can be called with some arguments (l...https://writing.codidact.com/posts/16085Documenting a Mongo Collection FieldShanimalhttps://writing.codidact.com/users/39832016-01-27T18:44:23Z2019-12-08T04:59:16Z<p>While writing some documentation I stumbled upon the need to describe the location of a field in a <a href="https://docs.mongodb.org/manual/reference/glossary/#term-collection" rel="nofollow nor...