Technical writing: Difference between revisions

(7 intermediate revisions by the same user not shown)

Line 8:

* Troubleshooting

== Software ~~documentation checklist~~ ==

== Software Documentation Checklist ==

* ~~Steps~~ by ~~steps process and screenshots~~

* Simplified Step-by-Step Guide with Visuals: [⭐ Beginner Friendly]

** ~~Is it possible to reduct~~ the ~~total~~ number of steps ~~in order~~ to ~~reduce the cognitive load?~~

** Consider minimizing the number of steps to lessen complexity for users.

** Include clear screenshots or diagrams for each major step.

** Difficulty: Easy - Visual guides help new users follow along intuitively.

* ~~Verify the entry point before using the software~~

* Clarity and Precision of Examples: [⭐ Beginner Friendly]

** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.

** Use real-world scenarios that readers can relate to.

** Difficulty: Easy - Examples are designed to be understood by all skill levels.

* ~~Copy & paste~~ the commands from the ~~documentation~~

Example for reference: How to get the source of id and hash values

** ~~The~~ PDF ~~will insert the line break~~ into ~~the command if the length of command is too long<ref>[https://stackoverflow~~.~~com/questions/18599711/how-can-i-split-a-~~shell-command-~~over~~-~~multiple~~-~~lines-when-using-an-if-statement syntax - How can I split a shell command over multiple lines when using an IF statement? - Stack Overflow]</ref>~~

[⭐ Beginner Friendly]

<pre>

{"id":"123","hash":"xxxxxx"}

</pre>

* Confirm Starting Point: [⭐⭐ Basic Experience Needed]

** Ensure the initial setup or entry point is verified prior to software usage.

** Include environment prerequisites and system requirements.

** Difficulty: Moderate - Requires basic understanding of system configuration.

* Command Replication: [⭐⭐⭐ Technical Knowledge Required]

** Instructions for directly copying and pasting commands from the guide.

** Note: Lengthy commands in the PDF might be broken into lines. Refer to this Stack Overflow discussion for splitting shell commands across lines.

** Difficulty: Advanced - Users should understand command line basics and syntax.

Difficulty Rating Scale:

⭐ Beginner Friendly - No technical background needed

⭐⭐ Basic Experience Needed - Familiarity with basic concepts required

⭐⭐⭐ Technical Knowledge Required - Understanding of technical concepts necessary

== ChatGPT Prompt for technical writing ==

Line 37:

Line 61:

- change "using 3D printing technology" to "using advanced printers to create tangible three-dimensional models."

5. ~~Finally, summarize~~ the article, ~~explaining it in one sentence.~~

5. Is there a disconnect between the message the article intends to convey and what the target audience perceives? If so, what are the reasons for this disconnect?

6. Finally, summarize the article, explaining it in one sentence.

</pre>

== Related pages ==

* [[Customer communication]]

* [[Quick start guide]]

== Further reading ==

Line 52:

Line 78:

[[Category:Programming]] [[Category:Software]] [[Category: Communication]]

[[Category:Programming]]

[[Category:Software]]

[[Category: Writing]]

[[Category: Communication]]

@@ Line 8: / Line 8: @@
 * Troubleshooting
-== Software documentation checklist ==
+== Software Documentation Checklist ==
-* Steps by steps process and screenshots
+* Simplified Step-by-Step Guide with Visuals: [⭐ Beginner Friendly]
-** Is it possible to reduct the total number of steps in order to reduce the cognitive load?
+** Consider minimizing the number of steps to lessen complexity for users.
+** Include clear screenshots or diagrams for each major step.
+** Difficulty: Easy - Visual guides help new users follow along intuitively.
-* Verify the entry point before using the software
+* Clarity and Precision of Examples: [⭐ Beginner Friendly]
+** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.
+** Use real-world scenarios that readers can relate to.
+** Difficulty: Easy - Examples are designed to be understood by all skill levels.
-* Copy & paste the commands from the documentation
+Example for reference: How to get the source of id and hash values
-** The PDF will insert the line break into the command if the length of command is too long<ref>[https://stackoverflow.com/questions/18599711/how-can-i-split-a-shell-command-over-multiple-lines-when-using-an-if-statement syntax - How can I split a shell command over multiple lines when using an IF statement? - Stack Overflow]</ref>
+[⭐ Beginner Friendly]
+<pre>
+{"id":"123","hash":"xxxxxx"}
+</pre>
+* Confirm Starting Point: [⭐⭐ Basic Experience Needed]
+** Ensure the initial setup or entry point is verified prior to software usage.
+** Include environment prerequisites and system requirements.
+** Difficulty: Moderate - Requires basic understanding of system configuration.
+* Command Replication: [⭐⭐⭐ Technical Knowledge Required]
+** Instructions for directly copying and pasting commands from the guide.
+** Note: Lengthy commands in the PDF might be broken into lines. Refer to this Stack Overflow discussion for splitting shell commands across lines.
+** Difficulty: Advanced - Users should understand command line basics and syntax.
+Difficulty Rating Scale:
+⭐ Beginner Friendly - No technical background needed
+⭐⭐ Basic Experience Needed - Familiarity with basic concepts required
+⭐⭐⭐ Technical Knowledge Required - Understanding of technical concepts necessary
 == ChatGPT Prompt for technical writing ==
@@ Line 37: / Line 61: @@
     - change "using 3D printing technology" to "using advanced printers to create tangible three-dimensional models."
-. Finally, summarize the article, explaining it in one sentence.
+. Is there a disconnect between the message the article intends to convey and what the target audience perceives? If so, what are the reasons for this disconnect?
+. Finally, summarize the article, explaining it in one sentence.
 </pre>
 == Related pages ==
 * [[Customer communication]]
+* [[Quick start guide]]
 == Further reading ==
@@ Line 52: / Line 78: @@
-[[Category:Programming]] [[Category:Software]] [[Category: Communication]]
+[[Category:Programming]]
+[[Category:Software]]
+[[Category: Writing]]
+[[Category: Communication]]