This is very much worth the 20 minute watch if you're writing documentation or trying to learn something new: https://www.youtube.com/watch?v=FKTxC9pl-WM
-- |
Administrator
|
I second that. This is a great presentation. -Dan On Wed, Jun 17, 2015 at 3:41 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan Allen | http://google.com/profiles/dan.j.allen |
I was just thinking about this talk on cognitive resources and how it relates to documentation and presentations.
Should we try to give smaller but more high-level examples of working code, examples that would be classified in box C, or distribute our examples over boxes A, B, and C taking our audiences cog. resources into account? How does this relate to documentation and the talks we give? For documentation I love showcasing small code block examples along with the describing text. In my opinion, this is where Asciidoctor shines. I find that most of my examples fit into box B, some in box C, and very few in box A. Maybe documentation should give an equal level of beginner, intermediate and expert level examples. For presentations I've always been told to try to stay away from showing code as its too hard to read and understand in such a small amount of time. I've never bought into this mindset as I'm typically presenting to developers who want to see something real and that works. Also, developers can often glance at a code block, as long as it's simple, and get the gist of the meaning. I'm beginning to think that we should be showing some more high level examples that expose these concepts in box C that also cover concepts in box B. I would love to hear your perspective on this. John |
I'm going to try doing more of type C, though honestly I'm not sure if you can group them that way. I see it more of a quantity AND quality issue. I think it's good to take people on the journey from A to C, hopefully skipping B. However, you can't do that without lots of examples. In talks, this is actually somewhat difficult. You'd probably need to have a bunch of code, but in digestible snippets. I'm not really sure how you would go about this in a typical 60 minute talk and be successful at it. Certainly worth discussing though. Perhaps a quick overview of a concept, then three - five examples of that concept then move on. However, I doubt you can cover many concepts that way. You'd almost need a series of talks to cover something well.On Thu, Jun 25, 2015 at 3:00 PM, johncarl81 [via Asciidoctor :: Discussion] <[hidden email]> wrote: I was just thinking about this talk on cognitive resources and how it relates to documentation and presentations. -- |
Free forum by Nabble | Edit this page |