Academy content

Docs Course/Raw/docs-course.asciidoc

@@ -0,0 +1,12 @@
+== A Documentation crash course for Web3 Developers
+
+
+
+
+
+
+
+
+
+
+=== Tools

Docs Course/Units/beyond-words.asciidoc

@@ -0,0 +1,11 @@
+In this module we cover:
+
+1.
+2.
+3.
+
+include::../posts/beyond-words.asciidoc[]
+
+== Test
+
+- TBD

Docs Course/Units/code-examples.asciidoc

@@ -0,0 +1,11 @@
+In this module we cover:
+
+1.
+2.
+3.
+
+include::../posts/code-examples.asciidoc[]
+
+== Test
+
+- TBD

Docs Course/Units/language.asciidoc

@@ -0,0 +1,11 @@
+In this module we cover:
+
+1.
+2.
+3.
+
+include::../posts/language.asciidoc[]
+
+== Test
+
+- TBD

Docs Course/Units/structure.asciidoc

@@ -0,0 +1,11 @@
+In this module we cover:
+
+1.
+2.
+3.
+
+include::../posts/structure.asciidoc[]
+
+== Test
+
+- TBD

Docs Course/Units/why-write-unit.asciidoc

@@ -0,0 +1,11 @@
+In this module we cover:
+
+- Why documentation is important
+- Who reads documentation
+- Removing assumptions
+
+include::../posts/why-write.md[]
+
+== Test
+
+- TBD

Docs Course/posts/beyond-words.adoc

@@ -0,0 +1,20 @@
+= Beyond writing
+
+For the most part we are producing documentation for delivery on the
+web, which is a rich platform that allows for more than pure text. I
+have already mentioned that images help break up the flow of walls of
+text, but good images also help illustrate a complex topic. While advice
+for creating video content is an entire subject in itself (maybe coming
+soon), they are also worth considering for newer developers, who tend to
+prefer them.
+
+Taking things up a notch, but a lot of fun for developers, is creating
+interactive documentation. This can mean anything from using the inbuilt
+API explorer tools that are often part of API hosting platforms such as
+https://apiary.io[Apiary], https://www.getpostman.com/[Postman] or
+https://swagger.io/tools/swaggerhub/[SwaggerHub], or using tools such as
+https://jsfiddle.net/[JSFiddle] and https://repl.it[Repl.it] to creating
+your own custom solution. The interactive approach (in any form) is one
+of the best ways to explain complex tools and what’s possible with them,
+but bear in mind that someone with the right skill set needs to maintain
+them, especially if you create your own.

Docs Course/posts/code-examples.md

@@ -0,0 +1,27 @@
+= Code examples
+
+Code examples are an essential part of developer documentation and help
+a developer understand a conceot, and as they are often the only thing a
+developer is looking for in your docs, they are essential to get right.
+
+Pick and use a consistent example to build upon. While it’s near
+impossible to address everyone’s nuanced use cases, using a consistent
+example helps a reader compare what they are reading to a concrete use
+case and read between the lines to apply to their use case.
+
+Aside from absolute first steps, make examples realistic and follow best
+practices for the language you are using. Overly simplified examples
+deter a reader, and reduce how seriously they take your documentation. Pick an example that can show introductory steps, but scale up to show more complex topics. Again, this helps readers extrapolate what they need to know for their particular use case.
+
+If you use long examples, consider adding comments to explain code lines
+in case a reader doesn’t read (all) the explanation.
+
+Test the code examples to see if they work, preferably on a different
+machine or virtual machine to your own, to prevent assumed dependencies, and the dreaded "works for me" statement. Some markup languages specific to
+documentation (not default markdown) allow you to embed lines from code
+files directly into your rendered documentation, meaning you can write
+a fully-functioning application that is testable. If that option
+isn’t open to you, then manually or automatically test code examples as
+often as possible. Remember that last time you found a code snippet that
+didn’t work, and how frustrating it was, and ensure it doesn’t happen in
+your docs.

Docs Course/posts/language.md

@@ -0,0 +1,104 @@
+# Language and understandable writing
+
+I appreciate that not everyone who writes documentation is a native
+English speaker, or even if they are, may not understand the best way to write clearly and concisely. Many native English speakers had our last
+grammar lesson more than 20 years ago, and have learnt the tips and tricks we now use as professional writers recently. There are three important things to
+remember to justify the time and effort of making your writing more understandable:
+
+-   English is often a default language for technical documentation, so
+    your readers are also not native speakers
+-   Readers want to trust what you say, and certain language choices can help
+-   Readers are trying to understand complex subjects, so every little
+    thing you do to make that easier is worth it
+
+While you can spend a lot of time crafting the perfect sentence to explain something, here are a handful of tips to add that dash of clarity your need.
+
+## K.I.S.S.
+
+> Or Keep it simple (stupid).
+
+Don't use words that add no value. Words for humour or character are fine
+(but come with complexity), but words that muddy the explanation (and
+thus the readers understanding) are a distraction. In English, there are
+words called [weasel words](https://en.wikipedia.org/wiki/Weasel_word) that add nothing but syntactical noise. They may be useful in fiction or
+creative writing, but for explanatory text, they are not useful.
+
+There are common weasel words that you probably use all the time without
+thinking, such as:
+
+-   very
+-   easy
+-   just
+-   only
+
+Certain weasel words such as "easy" and "just" are worse than noise, and they can come across as patronising. These are words
+that people commonly use, but don't think about their implications. If you say
+something is "easy", and someone spends 3 hours battling with
+dependency hell, then it wasn't "easy", and your documentation probably annoyed them. If you are lucky enough that your project, developer experience, and
+documentation is good quality then you don't need to tell people that
+it's "easy", they will find that out themselves.
+
+When you edit your first draft (which of course you should!), consider how many words you need to explain a concept. One of the advantages of English is that you can do quite a lot with few words, but many choose to use way more than they need. Continuing the theme of this section, every extraneous word adds syntactical noise that people have to sift through to find the information they need.
+
+## Show off
+
+There are words that people use to show off how clever they are,
+which is comparable to creating overly complicated code for no
+particular reason but to impress people. Remember that often when we write in
+English for technical copy (and it is often the lowest common
+denominator language in our sector), we are writing for international
+audiences, who are reading in their second or third language. Adding
+complexity for your indulgence is selfish and doesn't help anyone. If a
+simpler word does the job, use it. Let your code and ideas speak for how
+smart you are, not your knowledge of obscure English words.
+
+## Write confidently
+
+My final writing advice is a grammatical one, and something more subtle
+that I spend a lot of my time changing in the text that I edit, but I feel strongly about it. It's the topic of writing confidently. Confident
+writing helps people believe that what you say is true and accurate, and
+doesn't leave them unsure if they should believe what you say. There are
+a couple of small grammatical tricks to help with this that are
+sometimes hard to apply and may seem unnecessary but pay off in the
+end.
+
+Strangely, the best explanation is from [Stephen King's "on writing"](https://en.wikipedia.org/wiki/On_Writing_(Stephen_King)), even though it's not flattering of technical writing.
+The book is over ten years old, times have changed (I hope). In this
+extract, he starts discussing adverbs or words that modify other words. He then moves on to discussing the passive voice, which I cover next.
+
+> I think timid writers like them for the same reason timid lovers like passive partners. The passive voice is safe. There is no troublesome action to contend with; the subject just has to close its eyes and think of England, to paraphrase Queen Victoria. I think unsure writers also feel the passive voice some how lends their work authority, perhaps even a quality of majesty. If you find instruction manuals and lawyers' torts majestic, I guess it does.
+
+My first piece of advice is to active voice as much as possible. This means
+making it clear who the actor and subject are in each sentence. There
+are often situations where this isn't possible or relevant but try it as
+much as possible. It may not be clear what I mean, so here's an example.
+
+### Passive voice
+
+> Functions can be used to return a value
+
+Are you sure about that, can they or not?
+
+### Active voice
+
+> You can use functions to return a value
+
+Ahh, so I can use them!
+
+It's a small change, and might not even be that noticeable in isolation,
+but throughout an entire article, it does make a difference. It
+clarifies details, and the active voice gives readers more confidence,
+as the lack of clarity in passive voice can make it seem like you're not
+sure.
+
+### Confident words
+
+Another trick alongside this (and an example of English vagueness) is using more confident words elsewhere or removing less confident ones. For example, using "can" instead of "may" or "should", or telling the reader directly what they can do instead of making it sound like it's optional. For example:
+
+> You should add your key
+
+OK, I feel like I probably have to add my key, but it kind of sounds like it's optional.
+
+> Add your key
+
+Right nice and clear, I should add my key.

Docs Course/posts/structure.md

@@ -0,0 +1,149 @@
+# Documentation Structure
+
+Documentation structure applies to your documentation as a whole, and to each page. Let's start at the top and work down.
+
+There are different types of documentation your project might need. The
+terms I use to describe them below are just the terms I use, and others use different terms. The explanation of what they are is more important than what you decide to call
+them is up to you.
+
+## Documentation types
+
+### Getting started
+
+A Getting started guide is often a starting point with your
+project. It should take people from knowing next to nothing about your
+project to installing and configuring it, and performing their first
+interactions with it. The extent of what "first steps" means
+somewhat depends on your project, but it should be simple enough for
+anyone to complete, but complicated enough that it shows a semi-realistic
+use case that highlights the potential of your project.
+
+Let's take a hypothetical example of an SDK that allows a dapp developer to add the activity of a user from another site (say, a blog for example) to their dapp via an Ethereum address. The key components of this are a function that calls an API endpoint that returns activity based on an Ethereum address supplied as a parameter.
+
+With this in mind, a getting started guide might cover:
+
+-   Installing the SDK package (let's say it's available for JavaScript and Ruby)
+-   Including the library in an application
+-   The function that returns activity from the other application, with the address as a parameter
+-   Outputting that data
+-   Next steps
+
+### Guides
+
+Guides are a collection of documentation pages that take a user from getting
+started to the next steps. These are typically more in-depth around a particular topic or common use case.
+
+For the example above guides might include topics such as:
+
+-   Authenticating API calls
+-   Filtering the results from the API call
+-   Using the SDK without JavaScript or Python
+
+### Reference
+
+If your project has an API, error codes, or other particular components
+that need a reference, this is the place. If the rest of your
+documentation tells users how to use your tools to build something, this
+is the place where you explain what individual tools do. Often you can
+autogenerate these docs from code or other sources, and that's fine.
+Anyone digging into this section knows what they are looking for and is
+looking for specifics on how to use it.
+
+For the example above reference might include topics such as:
+
+-   Potential error messages
+-   All other API calls
+-   Full function and parameter reference
+
+### Explanation
+
+Perhaps most relevant to the Web3 world is a section for the theoretical
+underpinnings of the project. This is where you explain your consensus
+algorithm and encryption methods in depth. Again, not everyone wants or needs to know this information, but certain people will.
+
+## Documentation structure
+
+Creating good structure (or information architecture) for documentation can be a complex process,
+depending on how much documentation you have, the most important
+information people need to know, and the common pathways and questions
+they typically have.
+
+A good starting point is to divide your documentation along the lines of
+the categories outlined above, and then use feedback and analytics to
+tweak the structure over time. A typical alternative structure is to
+group documentation around use cases, and what a user might be trying to
+do, rather than arbitrary divisions. This doesn't suit all documentation
+projects, especially tools that a developer can use for nearly limitless
+applications, but can work well for focussed SaaS products.
+
+Another aspect to bear in mind is that no matter how much time you spend on creating the perfect organisation and navigation, a majority of readers arrive at your documentation from search engines. Once
+they arrive, they hopefully continue through the pathways you create, but there is still no guarantee of that. This means that you need to
+generally assume that someone arrives at a page with no knowledge of
+anything else in your documentation and you need to tell them what they should know before reading the page they arrive at. You can do this with
+an explicit pre-requisites section, inline links to concepts and steps,
+or with an expanding menu that won't always show a reader everything
+they need to know but does show them where the document sits in the
+wider structure.
+
+Finally, if possible, add multiple ways for people to find their way
+around your documentation, for example, a search box, related content,
+next steps etc.
+
+## Page structure
+
+Good page structure helps readers read. If a page is a wall of text,
+it's hard to process, and for people to find the details they are looking for. Good structure helps break up the reading experience, and
+draws attention to different topic sections, and important pieces of
+information.
+
+There's an unexpected bonus to using good page structure, and that's
+that it doesn't just improve readability for humans, but also for machines. Crawlers from search engines, digital assistants, semantic
+aggregators and more all have their work assisted by good, predictable
+page structure that follows best practices.
+
+### Correct and helpful headings
+
+Headings help readers identify what a particular section covers. Use
+correct heading hierarchy to indicate topics and sub-topics, but also to
+improve how machines read and understand the content. For example, to
+improve SEO.
+
+This means that a document should only ever have one top-level heading,
+typically a level one heading unless you are using a generator tool that adds top-level headings from tags or other sources of information.
+
+Subtitles should be level 2 headings, and any subtopics for those subtitles, level 3, 4 etc. You can use as many of these you need in a
+document, but be as consistent as possible.
+
+### Images and code examples
+
+As people scroll through a web page, their eyes are drawn to page
+elements that break up the wall of text. We are especially drawn to
+images, and developers are drawn to code examples as it's often what
+they are looking for most.
+
+The trick is ensuring that important explanatory text is around these
+elements, so after someone's eyes are drawn to it, they see the
+surrounding text and (hopefully) read it.
+
+We cover what makes good images and code examples in other sections.
+
+### Paragraphs
+
+White space is your friend in breaking up a wall of text, don't fear
+it. Every major concept, or half a dozen lines or so, start a new
+paragraph. Even better, if appropriate, add a sub-heading before it.
+
+### Highlighting and Formatting
+
+Make use of ways to highlight certain important pieces of information
+with formatting. I have my personal preferences which are:
+
+-   `Code formatting` for anything that is code.
+-   _Italics_ for paths and actions. Many use code formatting for paths,
+    but that doesn't make sense to me, as it's not code.
+-   **Bold** for important information.
+-   Any form of "double" or 'single' quote marks to highlight values to add somewhere, or the traditional usage of quote marks in the English language.
+
+But really what formatting you use for what isn't the important part,
+it's more important to be consistent if someone expects to see italics
+to show file paths, then stick to it.