-
Notifications
You must be signed in to change notification settings - Fork 10
/
DocumentationDraft.txt
60 lines (44 loc) · 4.31 KB
/
DocumentationDraft.txt
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
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
Plan for the documentation of the package.
General goals:
1) Readability (it should not be very hard to read)
2) It should not be necessary to understand the structure of the manual to understand the concepts.
3) Navigation to related topics should be very easy and intuitive.
4) The manual should be strongly modular.
5) The manual should give good terminal support (if called with ??)
For concreteness we employ several test-users as benchmarks:
Technician: Wants to know how to apply an obscure function in full generality.
Worker: Wants to use an elementary method but forgot the exact procedure. Wants an answer shortly.
Searcher: Doesn't know the package, searches for a functionality and wants to know if the package can provide it.
Perfectionist: Wants to understand the package and its functionality completely.
Casual: Wants to get a general perspective but doesn't want to invest too much time.
TODO: General problem: If someone goes into a chapter that is confusing/technical/complicated, they MIGHT skip it or go back.
But they also might be frustrated and leave. How can we make it clear that they don't have to get frustrated?
--------------
About the chapter ordering:
After the intro we start with "filters" to explain the general structure of this package (mainly to demonstrate PolygonalComplex and its relation to more specific filters).
Pro: People know what this is all about
Con: People might not skip and be bored by many different concepts
Then we have "Incidence", the access to the incidence geometry. This is a central chapter. It is after the "filters"-chapter since it is defined for the most general case (polygonal complexes) which the reader might feel confused about if they are not properly introduced.
Con: One can argue that the incidence geometry by itself motivates the definition of polygonal complex.. Then it should be first. (Although our definition of polygonal complex is more specific than the most general incidence geometry)
Rebuttal (Pro): The above argument is not completely correct. While it is true that "incidence" feels less technical than "filters" this does not hold if one considers the chapter length - while "incidence" spends a lot of time developing and explaining different ways to present the same information (which is mostly uninteresting), "filters" does focus on a lot of terms but it also develops them with specific examples in play. If it were the case that "incidence" was just a few pages long it could be in front of "filters" to make the focus more clear. As it is it would detract from the main point of the package - the surfaces and complexes.
Rebuttal (Pro): If we also consider when a linear reader will start skipping it should be clear that the first such point should be after an explanation of the basic package architecture. To show "incidence" first risks that the skipping point is before "filters" which would be a bad development. It would be more plausible to have "filters" first in this case as the information from "incidence" can also be gleamed by a casual reading.
After this more specialised chapters (like modifications and embeddings) follow (hopefully).
They should be behind the others as they are not really needed to work with the core processes.
TODO change this to
-> Constructing surfaces by their incidence structure
-> Constructing surfaces from other surfaces
-> Constructing surfaces from "nothing"(?) [this means data-base and examples, that could be better structured, like a section for platonic solids, one for random, one for doubleNgons...]
----------------
Chapter "Errors and bugs"
Goal: Document all possible error messages, together with explanation for their appearance and
how to resolve them.
Assume users find them by searching
Also include what to do if errors are found (how to report them etc.)
-> This does not need a separate chapter
-> Document error messages in the part of the manual where they are introduced
------------------
Chapter "Development methods"
TODO with example of wild simplicial surfaces (before they are introduced?)
TODO make clear in title that this is NOT intended for common usage
Chapter: "Database of surfaces"
this is not part of constructors chapter because it has several properties that are more than just construction.