Differences

This shows you the differences between two versions of the page.

--- appendix:guidebook_authoring [2018/08/15 14:41]
jguerin
+++ appendix:guidebook_authoring [2018/08/15 16:22] (current)
kericson [Terse is Almost Always Better] - better?
@@ Line 6: / Line 6: @@
 As coaches we also find ourselves sharing similar information year after year -- in practice sessions, in online discussions, etc. By putting the guidebook together we hope to create a single, enduring record of our thoughts and ideas. We also see no reason to keep this work internal because we are educators. By our very nature we wish to continue advocating for the spread of information.
-Finally, we are strong proponents of free and open source materials, so we wished to create something that anyone could use or adapt as they saw fit without any additioanl monetary investment up front.
+Finally, we are strong proponents of free and open source materials, so we wished to create something that anyone could use or adapt as they saw fit without any additional monetary investment up front.
 ===== Overview =====
@@ Line 12: / Line 12: @@
   * consistency in terms of structure (both overall organization and of page contents),
   * consistency in terms of tone (as though the entire endavor was written from the perspective of a single author),
-  * easy to locte information, driven primarily by working examples,
+  * easy to locate information, driven primarily by working examples,
-  * coverage of the broadest possible set of topics reltaed to the general field of computer science.
+  * coverage of the broadest possible set of topics related to the general field of computer science.
 While the guidebook is most likely going to originate out of the efforts of UT Martin professors/coaches and students, we hope to eventually have additional volunteers assisting with guidebook development.
 ===== Tone and Structure =====
+==== The Reader Is a Programmer ====
+  * While we hope that the guidebook will serve as a learning tool, our goal is not to teach //programming//.
+  * Articles should be written in a way that is accessible by programmers.
+    * Assume at least a semester of college level programming experience in //a// language.
+  * While the goal is not to teach //programming//, materials should seek to be self-contained.
+    * Just about every programmer understands variables and loops, but not everyone has experience with all conventions.
+    * E.g., Some imperative/object-oriented programmers may have less experience with lambdas, higher order functions.
 ==== Adhere to a Hierarchical Structure ====
+  * Try to use namespaces to preserve hierarchies.
+  * Sections, subsections, etc. should be hierarchical whenever possible.
+  * If you need to deviate from hierarchy (e.g., in a much lower level section header) you may be using the wrong tool.
+    * E.g., Footnotes may be clearer.
 ==== Whenever Possible, Speak Through Examples ====
+  * A well-written example will often say everything that you need.
+  * Try to build a reference around a series of instructional/useful examples of functionality.
+    * Algorithms will be handled differently by necessity.
+  * Many results can be explained //within// your code example with a quick comment.
+    * E.g., ''# x=5, y=6, z=[1,2,...,100]'' tells the user everything about the updates to variables on that line.
+  * Keep explanations minimal when they are necessary to understand an example, and keep them close to the example.
 ==== Start Simple, Build In Complexity ====
+  * As you construct your examples, start with trivial and end with complex.
+    * This is not necessarily at odds with a hierarchy, in particular if your (sub)sections are planned in the same way.
 ==== Terse is Almost Always Better ====
-The authoring page you are currently reading may serve as the worst example of this, but the need for detail here is probably going to be the greatest. (This will help to produce consistency elsewhere.)
+  * This page may be the worst example of this principle.
+    * Terseness in this page is sacrificed to produce consistency elsewhere.
+  * Keep editing to say everything in a few short statements.
+  * Pull content into auxiliary pages as necessary, make liberal use of links.
+  * Footnotes do a great job of retaining necessary text in place, but hiding it when it is not needed.
+  * Try to avoid excessive footnotes (many articles can suffice with an upper bound of 10-15 footnotes).
 ==== Back Up Your Claims ====
+  * Cite sources where possible.
+  * Include sources of algorithms/implementations.
+  * Where time complexity is a concern((E.g., most algorithm pages, the input/output sections.)) try to back your claims up with real world [[appendix:guidebook_authoring:benchmarks|benchmarks]].
+  * Always produce clean and commented sources in the ''files:'' namespace (or in a more appropriate location) so readers can verify your results.
 ==== Be Consistent ====
+  * While there may be several authors, the guidebook should be written from a singular perspective.
+  * Keeping other, similar guidebook pages in mind((Or on a secondary monitor?)) when you write can go a long way.
+  * The two first guidebook articles were selected to display the appropriate tone: [[python3:unpacking]] and [[algorithms:sieve:eratosthenes]] should serve as templates for future development.
 ==== Comment Your Edits ====
+  * Even the first author occasionally forgets. Don't be like him. Comment your edits.
+==== Formatting Tips ====
+  * Make use of single ''%%''%%'' quotes for all source in paragraph, ''<code>'' or ''<file>'' tags where appropriate.
+  * Use italics mode ''%%//%%'' for emphasis, highlighting industry terms, and variable names as a cheap (LaTeX) math mode replacement.
+  * Hack mathematical expressions with tags (e.g., ''%%<sup></sup>%%''), special symbols from the editor (e.g., ξ, ∑).
+    * Much of what we need to express for guidebook purposes can be written well (and look quite good on most browsers) with some creative hacking.
+    * Mathematics should be presented as we would typeset it in LaTeX.
+  * If examples emulate a shell, make it clear with symbols.
+    *  E.g., ''%%>>>%%'' for Python, ''$'' for arbitrary Linux shells (e.g., Bash).
+  * Present results as they would look in practice.
+=== C++ Conventions ===
+=== Python3 Conventions ===
+  * Avoid the shebang line. Overall it will net a significant savings.
+  * In Python, use single quotes for characters, double for multi-character strings.
+    * No, this is not required by the language, but keeps examples consistent where they otherwise may not be.

UT Martin Competitive Programming Guidebook

User Tools

Site Tools

Differences

Page Tools