Amazing video about creating great documentation / examples

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Amazing video about creating great documentation / examples

LightGuardjp
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

--
Reply | Threaded
Open this post in threaded view
|

Re: Amazing video about creating great documentation / examples

mojavelinux
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:
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

--



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Amazing-video-about-creating-great-documentation-examples-tp3402.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Amazing video about creating great documentation / examples

johncarl81
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
Reply | Threaded
Open this post in threaded view
|

Re: Amazing video about creating great documentation / examples

LightGuardjp
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.

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


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Amazing-video-about-creating-great-documentation-examples-tp3402p3440.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--