[UG] UG Comments

[AaronCQL]

Notes

• Title page with logo and team members name

Overview

• Explain the markups and symbols (note/tip/warning) used in the user guide (@AaronCQL)
• Explain what a caret is (maybe use text cursor?) https://en.wikipedia.org/wiki/Caret_navigation (@AaronCQL)

Quick Start

• Missing preamble/introduction (@AaronCQL)
• Might want to not use bullet points for the yellow box (maybe put under [TIP] and write full sentences) (@AaronCQL)

Commands

• Put add-c command as the first command
  • Follow CRUD (add-c, list-c, edit-c, delete-c)
• Avoid forward referencing
• list-c is not using numbers, might want to put after filter-c/find-c
• Alert the user to the Result Box after entering the command (alert success/error in other words)
• help: change explanation (leading to command summary or something)
• edit-c parameters preamble: no need to repeat
• add-e example: not complete enough - who are you adding the exercise to?
• delete-e: set the scenario (1-2 short sentences)
• export: set the scenario

Parameters

• Reword preamble: "This section shows the parameters and the important things to note about them:"
• In the table, use "Parameter" (no 's')

Example

• Set the scenario first ("For example, you want to add a client with these information...")
  • Can vary the language ("suppose you..", "imagine that...", "let's say...")
• After the scenario, use numbers to represent the steps

Common errors/problems

• Avoid repeating same points
  • Command Format already explains about optional and compulsory items, no need to repeat again
• Not critical to go into a lot of details and diagrams, user is already expected to understand the command in Parameter and Example
• Provide more concise preamble: "Here are some common problems that you may encounter"
• No need to provide diagrams about typing find-c bry (already explained in Example section)
• Change use of * to actual bullet points in parameters table
• Avoid numbering the subsections

Command summary

• Preamble required for sub sections (eg. under Client Commands: "These are the commands relating to manipulating the client details")