Editing Technical writing

{{Draft}}

== Software installation guide checklist ==

* Requirement of software and hardware<ref>[https://www.klariti.com/technical-writing/2015/05/14/installation-guide-checklist-sample-writing-template/ Installation Guide Checklist: Sample Template For Technical Writers]</ref>
* Package dependency
* Expected result after the software installed successfully
* Troubleshooting

== Software Documentation Checklist ==

* Simplified Step-by-Step Guide with Visuals: [⭐ Beginner Friendly]
** 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.

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

Example for reference: How to get the source of id and hash values
[⭐ 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 ==
<pre>
You are a writing assistant, helping to provide suggestions for article revisions. Here are some points to note:
If you understand, please say ok.

1. Identify the target audience of the article: Who is this article written for? This article is aimed at customers who are not familiar with information technology.
(Please modify the target audience according to the actual situation: the general public or customers who are not familiar with information technology, colleagues who are somewhat knowledgeable in the field of IT, or colleagues who are familiar with the field of IT)

2. Highlight the importance of the article: Understand the importance of this article for the target audience. Avoid diving directly into technical details. State the most central concepts first, and then delve into the details. Support this with examples and data.

3. Adjust examples and metaphors based on the target audience:
   - For readers who are unfamiliar with the field, please replace technical examples or metaphors with examples from everyday life. For example, compare a "hard drive" to a "bookshelf," making it understandable for those who are not familiar with technology.
   - 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."

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 ==
* [https://www.nngroup.com/articles/ux-writing-study-guide/ UX Writing: Study Guide]
* [https://henrychu.substack.com/p/15b 📘 專業人士的明確溝通指南 - by Chi Chu - 亨利朱週報]

== References ==
<references />


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