WEBVTT

1
00:00:00.000 --> 00:00:04.481
A README is useful when someone can follow
it without borrowing the author's memory.

2
00:00:04.864 --> 00:00:08.591
In this lesson, we will take a few
terse notes and turn them into a short

3
00:00:08.661 --> 00:00:12.503
setup path. The outcome is a
document that explains the purpose,

4
00:00:12.712 --> 00:00:15.510
prerequisites, starting
directory, first check,

5
00:00:15.603 --> 00:00:18.564
expected result, and recovery
from a common mistake.

6
00:00:18.889 --> 00:00:23.243
Use your previous Markdown exercise
or a fresh copy of checkpoint two.

7
00:00:23.568 --> 00:00:27.295
Consider this note: sensor
demo, compiler installed,

8
00:00:27.469 --> 00:00:31.010
run tests. It probably meant
something to the person who wrote it.

9
00:00:31.289 --> 00:00:35.341
For a new reader, almost every
important question is still unanswered.

10
00:00:35.584 --> 00:00:38.638
What does the demo do?
Which compiler is required?

11
00:00:38.812 --> 00:00:41.644
Where should the command run?
Which tests are relevant?

12
00:00:41.853 --> 00:00:45.197
What does success look like?
Improving the README means

13
00:00:45.278 --> 00:00:48.668
answering these questions in the
order the reader encounters them.

14
00:00:48.994 --> 00:00:53.301
Begin with purpose. Checkpoint two
prints a fixed synthetic report.

15
00:00:53.626 --> 00:00:57.689
The project will separate policy
from acquisition at checkpoint five,

16
00:00:57.898 --> 00:01:01.880
so shared C++ logic can
process controlled inputs.

17
00:01:02.205 --> 00:01:05.259
There is also a documented
firmware cross-build path.

18
00:01:05.502 --> 00:01:08.521
These are related activities
with different evidence. Say

19
00:01:08.591 --> 00:01:11.807
early that the core exercise
needs no physical board.

20
00:01:12.132 --> 00:01:15.720
A reader should not spend time
solving a hardware prerequisite

21
00:01:15.754 --> 00:01:19.342
that the lesson does not
have. Move to prerequisites.

22
00:01:19.783 --> 00:01:22.999
Link to the release's setup
document and dependency record.

23
00:01:23.382 --> 00:01:25.809
Avoid copying an incidental compiler

24
00:01:25.867 --> 00:01:28.630
location from your
computer into the README.

25
00:01:29.071 --> 00:01:32.369
That path may help you today
and fail for everyone else.

26
00:01:33.181 --> 00:01:36.188
A useful setup instruction
names the required tool

27
00:01:36.513 --> 00:01:40.170
and points to the supported
installation or configuration procedure.

28
00:01:40.554 --> 00:01:44.176
The release record identifies the
versions that were actually checked.

29
00:01:44.559 --> 00:01:46.451
Now establish the root directory.

30
00:01:46.776 --> 00:01:51.223
Open the project tree and identify
scripts, docs, host, and firmware.

31
00:01:51.548 --> 00:01:55.774
The README lives at this level.
Before presenting a relative command,

32
00:01:55.902 --> 00:02:00.313
write that it runs from the Sensor Monitor
root. A returning learner may have opened

33
00:02:00.360 --> 00:02:05.190
a terminal in the docs folder or in the
folder containing several exercise copies.

34
00:02:05.700 --> 00:02:08.707
The instruction should make
that difference easy to notice.

35
00:02:09.149 --> 00:02:12.504
Add the host-replay command
in its own PowerShell block.

36
00:02:12.887 --> 00:02:16.196
Use the exact supplied command
from the written lesson.

37
00:02:16.579 --> 00:02:21.084
Explain that it runs a reviewable
wrapper using the documented local setup.

38
00:02:21.409 --> 00:02:25.855
Keep the terminal prompt and surrounding
explanation outside the copyable block.

39
00:02:26.239 --> 00:02:30.175
A long line in a screenshot can
help someone recognize the screen,

40
00:02:30.418 --> 00:02:32.694
but the written lesson
must preserve a command

41
00:02:32.740 --> 00:02:35.190
that can be selected and copied directly.

42
00:02:35.794 --> 00:02:38.615
Write the acceptance
condition beside the command.

43
00:02:38.998 --> 00:02:40.972
The script must complete successfully,

44
00:02:41.181 --> 00:02:45.639
and its synthetic output must match
the documented fixed synthetic report.

45
00:02:45.883 --> 00:02:50.875
Do not fabricate a fixed all-tests-passed
line to make the README look finished.

46
00:02:51.258 --> 00:02:55.032
Your actual output belongs in a
result record tied to your checkpoint

47
00:02:55.090 --> 00:02:59.791
and environment. A clearly labeled
expected result is useful guidance.

48
00:03:00.116 --> 00:03:03.913
A made-up observation undermines
the whole reproduction path.

49
00:03:04.296 --> 00:03:06.734
Add a separate firmware-build subsection.

50
00:03:07.059 --> 00:03:10.705
The build wrapper preserves the
selected board target and options.

51
00:03:11.030 --> 00:03:15.128
A successful cross-build supports a
statement about compilation and linking

52
00:03:15.186 --> 00:03:18.866
for those inputs. It does not
establish that a board was attached,

53
00:03:18.982 --> 00:03:22.558
that an upload succeeded, or that
a sensor measured a temperature.

54
00:03:23.069 --> 00:03:27.237
Keeping this explanation near the command
helps the reader interpret success

55
00:03:27.307 --> 00:03:31.220
accurately. We can now add a
practical troubleshooting entry.

56
00:03:31.498 --> 00:03:34.703
Name it Script not found.
The first response should be

57
00:03:34.737 --> 00:03:37.872
to check the current folder
and confirm that scripts slash

58
00:03:37.988 --> 00:03:41.448
replay dot cmd exists
in the intended project.

59
00:03:41.773 --> 00:03:46.266
If the file exists elsewhere, navigate
to the documented root and retry.

60
00:03:46.649 --> 00:03:48.890
This is a focused recovery path.

61
00:03:49.400 --> 00:03:52.512
Reinstalling every tool
or changing broad security

62
00:03:52.582 --> 00:03:56.181
settings would hide the simple
question we need to answer first.

63
00:03:56.506 --> 00:04:00.871
Add a link to the hardware reference with
a sentence explaining when it matters.

64
00:04:01.254 --> 00:04:05.050
For example, read it before
changing board-specific settings.

65
00:04:05.433 --> 00:04:09.508
Follow the link in the rendered
preview and verify the file that opens.

66
00:04:09.950 --> 00:04:11.273
Return to the README.

67
00:04:11.598 --> 00:04:15.186
If the reader has to guess which
source applies to the selected board,

68
00:04:15.429 --> 00:04:19.075
your link label or surrounding
explanation needs improvement.

69
00:04:19.516 --> 00:04:24.566
Now perform the most revealing check:
follow your README from the beginning.

70
00:04:24.810 --> 00:04:27.863
Pretend that you have no
access to the old conversation.

71
00:04:28.247 --> 00:04:31.521
Do not silently fill a gap
because you remember the answer.

72
00:04:31.846 --> 00:04:35.491
If you change directory, locate
an unmentioned dependency,

73
00:04:35.735 --> 00:04:39.624
or use another document to understand
an option, record that gap.

74
00:04:39.949 --> 00:04:43.804
The next revision should make the
necessary step visible to the reader.

75
00:04:44.129 --> 00:04:48.031
When a check fails, classify
the failure before editing code.

76
00:04:48.356 --> 00:04:50.585
A missing compiler is a setup issue.

77
00:04:50.910 --> 00:04:53.638
A wrong directory is a navigation issue.

78
00:04:53.963 --> 00:04:58.758
A test reporting an incorrect result
may be a source or expectation issue.

79
00:04:59.083 --> 00:05:02.856
The README should direct the reader
toward the next discriminating check,

80
00:05:03.182 --> 00:05:07.094
not promise that one universal
fix solves every error.

81
00:05:07.535 --> 00:05:11.656
Record the actual message so the
recovery remains connected to evidence.

82
00:05:12.097 --> 00:05:13.746
If another learner is available,

83
00:05:13.990 --> 00:05:17.020
ask them to follow the procedure
and note where they hesitate.

84
00:05:17.345 --> 00:05:20.666
That is useful human feedback
when it actually happens.

85
00:05:21.049 --> 00:05:23.696
If you review the procedure
yourself or use an agent,

86
00:05:23.940 --> 00:05:26.680
label that review accurately. Do not turn

87
00:05:26.726 --> 00:05:30.488
an automated walkthrough into a claim
that a beginner has tested the lesson.

88
00:05:30.999 --> 00:05:33.703
Different forms of review
answer different questions.

89
00:05:34.087 --> 00:05:36.652
Your exercise is to
finish the six-part setup

90
00:05:36.699 --> 00:05:39.601
path and add one recoverable
troubleshooting entry.

91
00:05:40.042 --> 00:05:43.537
Run the first documented check when
the required tools are available.

92
00:05:43.862 --> 00:05:46.730
Submit the README and a
short record of link checks,

93
00:05:46.881 --> 00:05:50.283
command, outcome, and
unresolved prerequisites.

94
00:05:50.724 --> 00:05:55.136
If tool setup remains incomplete,
the document work can still be useful,

95
00:05:55.286 --> 00:05:58.247
but the executable path
remains an open check.

96
00:05:58.630 --> 00:06:01.602
Finish by inspecting the
diff and the rendered page.

97
00:06:02.043 --> 00:06:06.687
The diff should show a clearer procedure
rather than unrelated firmware edits.

98
00:06:07.128 --> 00:06:10.019
The preview should remain
readable in a narrow window,

99
00:06:10.193 --> 00:06:12.550
and the commands should remain copyable.

100
00:06:12.829 --> 00:06:16.370
You now have a README that does
more than describe a project.

101
00:06:16.648 --> 00:06:20.340
It gives the next person a way
to begin, recognize success,

102
00:06:20.491 --> 00:06:23.173
and recover when the first
attempt does not work.