Technical writing - Revision history

Planetoid: /* Related pages */

2025-02-03T08:59:48Z

← Older revision		Revision as of 16:59, 3 February 2025
Line 68:		Line 68:
	== Related pages ==		== Related pages ==
	* [[Customer communication]]		* [[Customer communication]]
			* [[Quick start guide]]

	== Further reading ==		== Further reading ==

Planetoid: /* Software documentation checklist */

2025-01-28T20:23:05Z

Software documentation checklist

← Older revision		Revision as of 04:23, 29 January 2025
Line 8:		Line 8:
	* Troubleshooting		* Troubleshooting

	== Software ~~documentation checklist~~ ==		== Software Documentation Checklist ==

	* Simplified Step-by-Step Guide with Visuals:		* Simplified Step-by-Step Guide with Visuals: [⭐ Beginner Friendly]
	** Consider minimizing the number of steps to lessen complexity for users.		** 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.

	* Confirm Starting Point:		* Clarity and Precision of Examples: [⭐ Beginner Friendly]
	** Ensure the initial setup or entry point is verified prior to software usage.

	* Command Replication:
	** 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.

	* Clarity and Precision of Examples:
	** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.		** 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.

	Example for reference: How to get the source of id and hash values		Example for reference: How to get the source of id and hash values
			[⭐ Beginner Friendly]

	<pre>		<pre>
	{"id":"123","hash":"xxxxxx"}		{"id":"123","hash":"xxxxxx"}
	</pre>		</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 ==		== ChatGPT Prompt for technical writing ==

Unknown user: /* Software documentation checklist */

2023-12-07T03:02:08Z

Software documentation checklist

← Older revision		Revision as of 11:02, 7 December 2023
Line 23:		Line 23:
	** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.		** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.

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

	<pre>		<pre>
	{"~~survey_id~~":"~~SURVEY~~","hash":"xxxxxx"}		{"id":"123","hash":"xxxxxx"}
	</pre>		</pre>

Unknown user: /* Software documentation checklist */

2023-12-07T02:49:44Z

Software documentation checklist

← Older revision		Revision as of 10:49, 7 December 2023
Line 23:		Line 23:
	** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.		** Evaluate if examples are straightforward and detailed, including explanations of fields and sourcing of specific values.

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

	<pre>		<pre>

Unknown user at 02:48, 7 December 2023

2023-12-07T02:48:39Z

← Older revision		Revision as of 10:48, 7 December 2023
Line 64:		Line 64:


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

Unknown user: /* Software documentation checklist */

2023-12-07T02:42:43Z

Software documentation checklist

← Older revision		Revision as of 10:42, 7 December 2023
Line 11:		Line 11:

	* Simplified Step-by-Step Guide with Visuals:		* Simplified Step-by-Step Guide with Visuals:

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


	* Confirm Starting Point:		* Confirm Starting Point:

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

	* Command Replication:		* Command Replication:

	** Instructions for directly copying and pasting commands from the guide.		** 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.		** Note: Lengthy commands in the PDF might be broken into lines. Refer to this Stack Overflow discussion for splitting shell commands across lines.

	* Clarity and Precision of Examples:		* Clarity and Precision of Examples:

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

Unknown user: /* Software documentation checklist */

2023-12-07T02:40:29Z

Software documentation checklist

← Older revision		Revision as of 10:40, 7 December 2023
Line 10:		Line 10:
	== Software documentation checklist ==		== Software documentation checklist ==

	* ~~Steps~~ by ~~steps process and screenshots~~		* Simplified Step-by-Step Guide with Visuals:
	** Is it possible to reduct the total number of steps in order to reduce the cognitive load?

	* ~~Verify~~ the ~~entry point before using the software~~		** Consider minimizing the number of steps to lessen complexity for users.

	* ~~Copy & paste~~ the commands from the ~~documentation~~
	** ~~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~~>		* Confirm Starting Point:

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

			* Command Replication:

			** 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.

			* Clarity and Precision of Examples:

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

			Example for reference:

			<pre>
			{"survey_id":"SURVEY","hash":"xxxxxx"}
			</pre>

	== ChatGPT Prompt for technical writing ==		== ChatGPT Prompt for technical writing ==

Unknown user: /* ChatGPT Prompt for technical writing */

2023-11-03T16:25:00Z

ChatGPT Prompt for technical writing

← Older revision		Revision as of 00:25, 4 November 2023
Line 37:		Line 37:
	- change "using 3D printing technology" to "using advanced printers to create tangible three-dimensional models."		- 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>		</pre>

Unknown user: /* ChatGPT Prompt for technical writing */

2023-11-03T03:34:15Z

ChatGPT Prompt for technical writing

← Older revision		Revision as of 11:34, 3 November 2023
Line 32:		Line 32:
	- If the reader is already familiar with the field, you can reduce or omit examples and metaphors.		- If the reader is already familiar with the field, you can reduce or omit examples and metaphors.

	4. Reduce jargon, explain in plain language: If the article is aimed at customers who do not understand information technology, try to avoid difficult professional terms and re-explain in simple language. For example, change "ERP system domain" to "a system that helps companies integrate the functions of various departments to improve efficiency"; change "researching UI/UX" to "studying how to make software and applications easier to use"; change "using 3D printing technology" to "using advanced printers to create tangible three-dimensional models."		4. Reduce jargon, explain in plain language: If the article is aimed at customers who do not understand information technology, try to avoid difficult professional terms and re-explain in simple language. For example,
			- change "ERP system domain" to "a system that helps companies integrate the functions of various departments to improve efficiency";
			- change "researching UI/UX" to "studying how to make software and applications easier to use";
			- 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. Finally, summarize the article, explaining it in one sentence.

Unknown user at 03:27, 3 November 2023

2023-11-03T03:27:29Z

@@ Line 17: / Line 17: @@
 * Copy & paste the commands from the documentation
 ** 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>
 == Related pages ==