Skip to content

Welcome to MkDocs

For full documentation visit mkdocs.org.

WRIT 5662 Lightweight Docs Assignment

I began my journey into markdown with Dr. Card's GitHub website, which gave me a comprehensive overview of how and why it is used. Next, I watched a few tutorials on LinkedIn Learning to gain knowledge about specific features that I was unfamiliar with, such as links, images and line breaks. I was unable to get the blockquotes to work in MkDocs, but it works when I plug it into StackEdit. What shall one do when beleaguered by such trivialities?

LavaCon 2020 Summary

I thought that there was a very diverse lineup of presentations to choose from. There were even topics that I had never thought of before. Some presentations used real world examples with practical implementation whereas others focused on theory. Personally, I found value in both! I did watch one presentation that was a bit too informal where I tuned out after five minutes. I felt that the speaker was not prepared or should've just read from a script. I'm guessing this was just an isolated incidence, considering the other three presentations I watched were very insightful.

Presentation 1: Topic Writing Without Borders

Summarized by the one and only Cal U'Ren

Overview

This presentation reiterated that people are bombarded with more information than ever before each day. The average person is hit with approximately 105,000 words a day. That’s 23 words every second in a twelve-hour day which adds up to roughly 34 gigabytes of data. The writer's goal is to capitalize on the user’s 50 bits per second. If you are legally obligated to share certain information, then jargon and complex sentences are acceptable, but otherwise try to avoid them. People should know when they’re about to engage with dense material.

Key Takeaways

A writer’s goal is to capitalize on the user’s 50 bits per second.

"No one is going to sit there and read your manual from cover to cover. People are going to come at it from all different kinds of angles to tap into what they need to get on with their life.

Cognition = comprehend + retain

Say more with less:

  • Remove distractions
  • Avoid stating the obvious
  • Eliminate long complicated sentences
  • Remember that the reader is an active participant

Reflection

This presentation connected with a bunch of the Redish text in regards to user accessibility and usefulness. They both gave identical advice in many instances, especially for visual design and how to structure headers and lists in a way that didn't detract from comprehension. The LavaCon presenters were adamant that users do not inherently value your work and they were cynical about users' motives as well. They felt that content creators should assume people are lazy or are overwhelmed with information each day. They used this notion as the foundation for their argument to implore technical communicators to make their content stand out. Redish did much of the same, but implored us to use strong rhetorical components and website design, so as not to inhibit the user experience. Since users are given so much content, it's imperative that you don't shoot yourself in the foot.

Slide on Minimalist Topic Based Authoring

Presentation 2: Beyond Inclusion: The Importance of Accessible Web Content and Design

Summarized by yours truly, Cal U'Ren

Overview

The majority of websites are not Web Content Accessibility Guideline (WCAG) compliant. This is problematic since there are 22 million working-age adults in the US with disabilities. That’s an immense number of underserved individuals with a lot of buying power. There are also many people who would benefit from WCAG compliance outside of the disabled:

  • People who use small screens
  • Aging population
  • Folks with temporary disabilities
  • Situational limitations (Examples: bright sunlight, contrasting colors)

Why is Accessibility Important?

Key Takeaways

When tackling WCAG compliance, the speaker recommended a few parameters to work around. Here is the “getting started” with accessibility checklist.

  • Choose a conformance level
  • Audit a segment of your website
  • Publish an accessibility statement

A few simple suggestions from “Beyond Inclusion: The Importance of Accessible Web Content and Design” that every web designer could easily implement.

  • Create “alt attributes” that are appropriate
  • Have enough contrast between backgrounds, buttons and texts. Don’t hamper the user experience. Meet the standards for accessibility.
  • Video: Don’t allow auto-play
  • Links: Avoid “click here” and “learn more” - similar advice to our Redish readings!
  • Be specific: Use anchor text that’s clear outside of context

Reflection

This extends our previous work with the MN Healey Club and their unique user group containing old people with poor eyesight and low technological literacy. Our group discussed how this impacted web design but did not approach the issue with WCAG guidelines in mind. In fact, we had no idea they even existed, which seems to be the real issue. Knowing which standard of WCAG compliance we hoped to achieve would've been a strong goal to work towards from the inception of our project. It also would've made a huge difference for all of the Club's users! I believe WCAG compliance should've been something that was discussed in Dr. Card's initial meeting with Daphne to establish parameters for us as we worked. I'm not sure how to make WCAG guidelines more prominent in technical communication, but it seems that it could only help.

Presentation 3: Building Content, Building Success

Summarized by your dear companion Cal U'Ren

Overview

This presentation followed the National Center for Construction Education and Research (NCCR). The organization is based in Florida and describes itself as effectively the gold standard in construction education and certification. Global demand drove them to consider how they were publishing. All sorts of markets desperately needed their information to bring discipline and predictability to their trades.

“This is non trivial. It’s good that someone does it and that someone does it well.” - Joe Gollner, the keynote speaker.

Through these investments, NCCR is trying to get ahead of the curve by developing processes that introduce a lightweight CMS that delivers process facilitation and asset revision control. They needed to be more nimble and to be able to adapt with a lightweight approach to content management.

NCCR's lightweight CMS infrastructure

  • Git repository
  • Cloud Digital Asset Management (DAM) platform

For a visual representation, check out Joe Gollner's Flowchart.

Key Takeaways

The global market is increasingly demanding more output, making production and automation more important than ever. This forces organizations to scale up and requires them to be more nimble and adapt. Large companies cannot be siloed; they need a lightweight approach to content management. Through these investments, NCCR is trying to get ahead of the curve by developing processes that deliver strong facilitation and asset revision control. Similarly sized organizations in disparate industries would be served well by following a similar approach. Joe Gollner, the speaker, sums it up well: “Shorter cycles, better adaptation, faster delivery.”

Reflection

NCCR's approach to content management demonstrates the value behind using the correct tools for specific tasks. Frequently, we use what is familiar or convenient, yet there are countless digital tools that are best suited for what people need to accomplish. In this class, I've learned how different coding languages can enhance website design. By blending knowledge of different languages into one final product you have more freedom to implement content in a rhetorical manner. You are no longer limited in how you present information, which is crucial for user credibility and usefulness. For example, diving right into Adobe XD before consulting with users might not be a sound approach. You also might want to build a website's structure through markdown first, before transitioning to HTML, thus saving yourself a significant chunk of time. If there are lots of tables, lists or other elements that necessitate time, then you want to use the tools that streamline your workflow.