1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
|
In lack of good git documentation and manuals, I started by own.
This manual is aimed at technical people.
It seems to be lack of well written manuals, and Git's online
documention itself is atrocious. While I do not except the
writers to have taken any course in pedagogy or didactics, or
even have any practical experience, I at least expect the
writters to try to keep those aspects in mind, but that does
not seem to be the case.
Documentation should first introduce the concept, then the
implementation; that is, first how to get started, than what
they are doing*. In other words, first how to create a Git
repository and the absolute essantials, than introduce Git
itself. Not first taking about what Git is, readers want to
read the chapters in their order, if they do not have anything
specific in mind.
Documentation should then give you breif a documentation of
everything you need to know in the order of its imporantance,
then, iterate to the more advanced.
But one of the most important part is not to start with
dangerous commands just because it is easier to be lazy with
them. Try to do it right from the beginning, otherwise the
wrong way will stick in the reader's memory.
* This is a concept called ‘concrete before abstract’. While I
disagree that it is always the best practices, I do think so
in this case.
|
