This is a machine-translated text that may contain errors!
Pen a User’s Guide
In brief summ’d
- A user’s guide aideth a certain soul to perform one singular task.
- Each step containeth but one action, and declareth what the user shall behold thereafter.
- The guidance remaineth incomplete until he that knoweth naught of this system hath follow’d it through.
To Whom Shall It Be Given Use?
Evermore first inquire thou shalt: To whom shall this guide extend its aid, and what deeds must they have wrought when their labour is complete?
A fresh hireth of the IT craft, well-versed in the art of the terminal, requireth a distinct instruction from that teacher who hath never once opened one. Thus may it be required by the same system to possess multiple guides. Discern thou what knowledge the recipient already possessest, unto which things they hold access, and those words unknown unto them.
What manner of document is this?
A user guide is a guide to action: it aideth the user in the accomplishment of one task alone. It be no textbook, nor a compendium, nor an explication of why the system doth function as ‘tis wrought.
| Document Type | The Reader Asks | Example |
|---|---|---|
| Guide to Action | How dost thou accomplish this? | Thus shalt ye publish a new version of the application |
| Instruction | How may I learn this matter? | Thy first vessel, step by step |
| Reference | What is the value or commandment? | A list of ports and services |
| Explanation | Why doth it behave thus? | Wherefore we employ a reverse proxy |
Should the reader require elucidation along their journey, keep’t brief and place it where the soul of the user doth need it most.
The Parts of the Guide
| Part | What it doth answer |
|---|---|
| Goal | What hath the user attained when this guide is followed? |
| Before thou begin | Which accesses, programs, files, and prior knowledge be required? |
| Step-by-step | What doth the user perform, in what order, and what should they behold after each step? |
| Examples | How do a command, a setting, or a correct result appear unto thee? |
| Troubleshooting | What shall the user do if the outcome differs from expectation? |
| If thou mustst undo | How may one reverse an alteration that went awry? |
| Checklist | How doth the user verify all things are right in the final reckoning? |
| Important Tips | What hast thou learned which the user ought to know? |
| Sources and Verification | Upon which sources, versions, and testing grounds does this guide stand? |
How to Pen a Steppe
These precepts rest upon standards for manuals of use and documentation for the user (IEC/IEEE 82079-1 and ISO/IEC/IEEE 26514).
- Commence each step with a verb in the imperative form: “Open,” “Run,” “Verify.”
- Let one action befall per step, and one instruction per sentence. Keep thy sentences beneath some twenty words.
- Declare what the user shall behold when the step is done.
- Place warnings before the step they concern, not after.
- Employ the same word for the same thing throughout. If it be called “the terminal” in one place, let it not be named “the console” in another.
- Explain a term of art at its first usage.
A feeble step:
Set up the web page and verify that all things work aright.
A Better Step:3. Prickse thy configurations
Execute thou this command:
sudo nginx -tThou shalt behold:
nginx: configuration file /etc/nginx/nginx.conf test is successfulIf other things to thine eye appear, proceed unto “Troubleshooting”.
Commandes, Anticipated Resultat & Placeholders
- Place thine commands within a code block, and thy anticipated result in a separate block beneath it.
- Employ code formatting for filenames, file paths, and commands in running text, e.g.,
/etc/nginx/. - Never inscribe veritable passwords, keys, or internal addresses. Utilize distinct placeholders:
<server-ip>,<username>,<domain>. - Keep lines of code below approximately 70 characters, lest they be severed upon parchment.
Troubleshooting
Frame thine debugging about that which the user beholds:
Ailment → probable causes → inquiry → remedy → confirmation
| Signe | Probable Cause | Examine | Remedy | How thou shalt perceive ‘tis resolved |
|---|---|---|---|---|
| The web page doth display “502 Bad Gateway” | The service behind answereth not | Run docker compose ps and see if the vessel be in motion | Set the vessel to work with docker compose up -d | The page loadeth, and docker compose ps sheweth “Up” within the column of STATUS |
The method whereof speaketh is found in [[Feilsokingsmetode Level 1 - Systematisk feilsøking|Method of Seeking Faults]].
Screen-Shots
Employ a screen-shot solely when it aideth the user to discern a rightful outcome. Crop the image, mark that which is of most import with an arrow or a numeral, and expunge any sensitive tidings. Pen an alternate text declaring what the picture doth display.
- Windows: Windows-key + Shift + S
- Mac: Cmd + Shift + 4
Print unto Parchment of Portable Document Format
- Unveil the guide within the preview pane of Visual Studio Code, or open the tome upon GitHub.
- Choose to print thy work. Upon Windows: Press Ctrl + P. Upon Mac: Press Cmd + P.
- Select the option to “Save as PDF”.
- Peruse the pages thereof. Ensure that no lines of code, tables, nor images are severed from view.
Obtain Feedback Ere Thou Dost Deliver
Bide thou hast thy fellow-student read the guide ere thou proclaime it done complete. He that giveth reply shall speak brief and point unto the very place within the text:
- Veracity: Be there steps or claims upon which dost doubt remain?
- Audience and Order: Is it plain unto whom this guide is writ, and what must be in order first?
- Language and Action: Doth each step hold but one deed and a result expected? Are terms of art expounded?
- Security: Lurketh any matter not fit for public gaze?
Bestow two strengths and two distinct improvements. Be kind and specific: “I counsel that thou explainest proxy in the second stage, because…” availeth more than mere “unclear.” Of giving feedback thusly: NDLA How to give feedback?.
Task I - Make Weak Steps More Strong
Rewrite each step so that it hath one verb in command form, one action, and an expected outcome. Divide those steps which contain more than one deed.
- “Now the container must be started, and it is to be checked if it runneth.”
- “Change the configuration, and mind ye test it after, then load it anew.”
- “Enter upon the server with the password Sommer2026! and go unto the folder of the webpage.”
Task II - Pen a Brev Guide
Chuse an endeavour thou mayest accomplish without aid, to wit, the launching of a vessel-container or the publication of a change upon a web-page.
- Scribe unto whom this guide is intended, and what they shall possess the ability to perform thereafter.
- Set down three unto six steps with their expected outcomes.
- Append no less than one line unto the remedy of errors.
- Permit a fellow scholar to follow this guidance without thine explication thereof. Amend that wherein he doth halt.
Further to peruse
- NDLA: To devise manuals of use and information for sundry sorts of folk
- NDLA: To craft materials for instruction
- The Council of Tongues: Plain Speech
- Diátaxis upon the four kinds of writing (in English)