Technical writing

From LemonWiki共筆
Jump to navigation Jump to search


icon_scale_pencil.png 這篇文章「Technical writing」內容還在撰寫中,如果有不完整的部分,歡迎你直接動手修改


Software installation guide checklist[edit]

  • Requirement of software and hardware[1]
  • Package dependency
  • Expected result after the software installed successfully
  • Troubleshooting

Software documentation checklist[edit]

  • Simplified Step-by-Step Guide with Visuals:
    • Consider minimizing the number of steps to lessen complexity for users.
  • 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: How to get the source of id and hash values

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

ChatGPT Prompt for technical writing[edit]

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.

Related pages[edit]

Further reading[edit]

References[edit]