Tag: Write The Docs EU

Session notes from Write the Docs EU 2014, a conference in Budapest, Hungary about crafting great documentation.

Write The Docs EU — Fintan Bolton — The community wrote my docs!

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Is community–written documentation a good idea? Absolutely. As an example, Red Hat had 6,000 pages of documentation — 1,000 were from the community.

Wikis are powerful:

  • Low barrier to contribute.
  • Instant publication and gratification.
  • Zero learning curve (almost).
  • Editable as plain text.

Pros for DocBook/DITA:

  • Good formats for archiving docs.
  • Rich markup vocabulary.
  • Precise and well–defined syntax.
  • Sophisticated build options (e.g. conditions and profiling, includes and con refs, entities)

What’s the impedance mismatch between the community and corporate documentation?

  • Variable quality (e.g. formatting, style).
  • No versioning.
  • Inappropriate content (stuff you wouldn’t want to support, inaccurate claims, spam)

Synchronizing community and product documentation. Rather than tracking community–generated docs and merging with product docs, track community–generated docs from previous community–generated doc changes, then convert the latest iteration into the product docs. Don’t clobber the work of other contributors, lest you lose popularity. Keep in mind that competitors will use comity–written docs.

In conclusion, integrating community–written docs is a big issue, and involves more than a conversion tool. On the flip side, there can be big rewards.

Fintan Bolton is from Red Hat.

Write The Docs EU — Christine Burwinkle — Pairing with designers to create a seamless user experience

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Christine is a tech writer from Atlassian, who is best known for Jira and Confluence.

  • Went from five to thirty designers in the last two years.
  • Goal: Help casual users, too!
  • Ten tech writers, 400 developers.

Techniques borrowed from designers are used for their writing.

Three main design principles (printed and framed, hanging on their office wall):

  1. Be familiar
  2. Grow with me (help users become power users)
  3. Give me clarity

Aside: Android UX principle is her personal favorite.

Audience/Personas — they printed them everywhere.

Designers took a year–long project:

  1. What role is a feature targeting.
  2. What is assumed skills/background
  3. How do

Leverage data from designers to help them craft better documentation.

Measure success by piggybacking:

  • Usability testing to determine if they need documentation, and publishing FAQs (if necessary).
  • Analytics results.

Diving into borrowing design techniques

Workshopping example: Empathy maps (to bring focus to the user)

  • Better understand their feelings “before and after” a situation
  • Work backwards from the “after” situation to create an ideal state, and empower users.

They’re huge fans of Post–Its:

  • Easy to move ideas around.
  • Excellent for separate collaboration and brainstorming.
  • Inexpensive, mobile, and fun!

Workshopping example: Sparring sessions

  • Critique session to bring group thinking into design and planning.
  • Confirms if goals are met with the prototype.

Sparring with TWs (technical writers)

Before the session, TW sends:

  • Draft to discuss
  • List of goals in the document

Superb sparring session tips

  • Timebox!
  • If your team is given to negativity, try positives–only for five minutes. Fantastic idea!
  • Make sure everyone is heard. Use a checklist, or give everyone one minute to list feedback.
  • Leave with at least three action items.

Workshopping example: 6–ups

  • Divide a sheet into six parts.
  • Focuses on ideal solutions.
  • Gets out of thinking in words. (Draw!)
  • Great method to build on ideas from colleagues.

Workshopping example: User stories

  • How does a user get to a feature? Is it controlled? From many different areas with different goals?
  • What does a user do before? What do they (usually) do next?
  • If they fall out of line in the process, documentation is needed for additional context.
  • Lo–Fi: Use colored stickers to “vote”, then build the document plan based on problem areas.
  • Australian slang: “Doco” is short for documentation. 🙂

Finding the right projects — look for:

  • A team that finds value in design and tech writing.
  • A designer who sees value in the docs
  • A new project that’s running lean and has some momentum.
  • Look for projects that are data–driven.

Explore and expand

  • Read design principles and techniques.
  • Follow UX blogs.
  • Write a documentation experience plan.

Write The Docs EU — Robert Lehmann — Self-Directed Learning Material

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Don’t teach dogmatically.

Collaboration can kill cohesion, so choose one champion for the discussion.

Use the right tools and lightweight markup; they use Jekyll and Sphinx.

Begin with the end in mind. For example, when you start to explain a process, if you mention a few things that haven’t been covered before, backtrack and write that information in a new (earlier) chapter.

Encourage experiments so people can appreciate going through the exercise and learning from it. On a related note, “no pain, no gain”.

Being redundant is good, but being concise is better. Find balance between the two.

Translate verbatim and sheepishly. If you spot anything wrong, update the original source first.

How do they teach?

  • Teachers need to remember that “their keyboard is made of lava”. Instruct the students to do it.
  • Use the Socratic method. Don’t give answers. e.g. “Good question! What could you do?”
  • “Feedback is the breakfast of champions.”

For more information, see Coaching Guidelines.

Write The Docs EU — Tom Christie — Designing MkDocs

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

MkDocs is used to create project documentation with Markdown.

Background:

  • Needs documentation for open source projects, such as the Django REST framework.
  • Documentation is the design for the product.
  • Built a custom–script to redo the Django REST framework — which was hard–wired to that specific project — and MkDocs was born!

(As an aside, Tom is a fan of the simple aesthetic of the Mou editor, which allows him to visualize the document rather than using a regular editor.

Requires Python and pip, install took about thirty seconds. Has a single configuration file (YAML). Will automatically reload the content after editing any of the source, configuration, or theme files.

  • Use relative links.
  • Documentation will be hyperlinked in the editor.
  • Use references to target a page or title anywhere in the documentation.
  • Name the linked title explicitly (if needed).

Some configuration options:

  • site_name (required)
  • site_url
  • site_description
  • repo_url (like GitHub)
  • copyright
  • google_analytics

Custom themes are available (see the Bootswatch project.)

mkdocs build builds the site to the “site” directory for static site deployment, such as GitHub pages or Amazon S3. (MkDocs already includes GitHub page support.)

Focus of MkDocs:

  • No programmatic API.
  • No embedded documentation.
  • Not a semantic markup tool.
  • Markdown only.

Lastly, the 1.0 release is in progress, and he needs help, so contact him if you’re interested. Very slick! 🙂

Write The Docs EU — David Hooker — What I have taught developers about writing

David Hooker

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

What makes us write?

  • We’ve created something we’re proud of, and want the world to understand and use it, and make the world better.
  • More common reason: we want some love.

Increase our corridor high–five count

Video clip from The Simpsons, Season 5: “Homer Goes to College” (regarding jocks versus nerds)

“Geeks shall inherit the earth” — and the jocks tremble. 🙂

Despite the world changing and geeks have money, power, respect, and women (not in that order), what do geeks still lack? Social skills.

New currency is smartness.

Fix my problem vs. Fix my emotions

Best way to get an attachment is to play on their emotions.

“It doesn’t matter if you can tell an engineer wrote it.” (Translation: It doesn’t matter if it’s boring.) BS!

Five movies that all engineers love (from his non–scientific poll):

  • Matrix
  • Matrix Reloaded
  • Inception
  • Blade Runner
  • Star Wars

Why? All written by geeks. All are love stories.

Point: We all love emotional attachment.

How do we get there?

  1. Start with the good sh*t. Example: The Matrix introduction. (What about Star Wars? Bah. No one has the patience anymore.)
  2. Keep it simple. Examples: Football diagrams comparing Brazilian/Spanish goal vs. English goal. Hemingway. For Sale: Baby Shoes, Never Worn. Intrigue in six words.
  3. Write the sh*t people say. Refers to Chicago Manual of Style 5.2. If you get one annual subscription, get the Chicago Manual of Style.
  4. Don’t repeat sh*t.

When we took these four rules to the Prezi engineering blog, it was picked up by The Guardian Blog as one of the engineering blogs you should read.

Write The Docs EU — Jessica Rose — Tone in Documentation

Jessica Rose

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Most Important Thing: Reinforce your brand’s voice, but don’t make it sleazy.

How do you want your users to feel about you?

Tone can also:

  • communicate your intended audience.
  • communicate your expectations for how they will (or might) interact with your product.
  • indicate the level of interactivity you’re willing to maintain with your clients or users.

Be willing to make updates or changes.

Communicating audience expectations

  • skill level
  • level of investment
  • individuals or organizations
  • commercial or non–commercial

Common problems with user expectations and tone

  • Misjudging your audience.
  • Limiting your audience through tone of the wrong level.
  • Writing for yourselves, rather than your users.
  • Using culturally limited references can exclude potential users.

Setting expectations with tone.

Level of Creativity

  • What kind of limits, if any, do you want to set?
  • Do you expect user to confirm to a level of professionalism or a specific niche?
  • Are you inviting them to try and break something?

Aspirations for Users. Encourage ten to do more.

Challenges in Setting Expectations for use through tone

  • Setting too narrow a scope for expectations is going to limit your more creative potential users
  • Setting too wide a range of expectations for your users is going to panic lower–level users.
  • Trying to set multiple levels of user expectations can get messy.

Setting communication expectations

Setting the tone for interaction

  • What kind of resources are you making available for user support?
  • Are you building a community?
  • How accessible do you want to be to your users?
  • What level of transparency are you aiming for?
  • Public or private communications?

Examples:

  • She’s a fan of Buffer because of their tone. For example, their “Questions & Problems” section. Echoes their brand awareness and transparency.
  • Ember.js also has great tone and documentation.
  • Wikipedia
  • CoffeeScript. Their branding is their documentation. Not as accessible. Not very much comforting language, or a personal connection.

When is it important to divorce from your branded tone?

  • When your audience for documentation and main products diverge.
  • When the branded tone is inappropriate.

Example:

  • Yelp has a distinct, happy branded voice. Very cheerful, bouncy, yet patronizing. Their developer documentation is dry.

Divorce or dilute?

  • Facebook has a unique branded voice. “Hey, we’re Facebook, we have your family!” Documentation is slightly watered down to break out of the Facebook stalker bits.

Takeaways:

  • Who are my users?
  • What do I expect them to be doing?
  • How much interaction do I want to promise?

Write The Docs EU — Jannis Leidel — Search and find. How we made MDN discoverable

Jannis Leidel

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

MDN: Mozilla Development Network

Current system, based on Kuma, allows them to display the information they deem fit for how they want their sites to be displayed.

  • Responsive design
  • Content zones
  • Search is front and center

Search

  • Migrated from custom Google search to own implementation
  • Full text, multi–lingual
  • Faceting, filters, pagination

Search Filters

  • Extensible via admin UI
  • Based on document tags
  • Topics, skill level, and document type currently

Search API

  • Every search page is available as JSON.
  • Includes are metadata to programmatically use the search.
  • Creative Commons license!
  • Search result navigator on document pages.
  • Coming from search page.
  • Documentation status page (processed through Kumascript). Slick!
  • Command and query.
  • Quick access to filters with shortcuts.
  • Extensible UI for suggestions.

Search CLI

  • Developer toolbar integration
  • Source code inspector

Search future

  • Code editor integration via plugins.
  • User profile search with @user syntax.
  • docs.json integration.

Write The Docs EU — Thomas Parisot — README Driven Development

Image

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Strive for simplicity so you can spend time doing the things you want to do.

Choose the tools.

  • How do you install (blah)?
  • How do you configure (blah)?

More bullet points:

  • Strive to satisfaction, and love the work you do.
  • Choose the most simple markup so you can quickly learn, write, and read.
  • Answer these basic questions — who, what, why, where, when, and how?
  • Display readme documentation alongside with example code.to provide context.
  • Keep the document size shallow. “Trust your gut feelings.”
  • Make the document crystal clear with ourself, team, and contributors.
  • What is the intention of your code? How are people going to use it? Will it make sense?
  • Fix bugs before writing the documentation.
  • Code sketching is fast, straightforward, and easy. Quick to iterate.
  • Content First. Technicity states back.
  • Detect complexity by breaking your code.
  • Suggestion: It’s better to split pull requests.
  • Issue the intention by telling the code owners what you’d like to do.
  • mdlint validates code in Markdown files.
  • Bring everyone into the process by making the dialog easier. Improve code quality. Keep it simple.

Write The Docs EU — Markus Zapke-Gründemann — Writing multi-language documentation using Sphinx

Markus Zapke-Gründemann

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Sphinx – Python Documentation Generator

Supports many output formats.

Internationalization (i18n): Translate into other languages without changing the code. GNU gettext is used frequently.

Tip: Install sphinx-intl to make it easier to setup.

Better to setup more automation. He found himself writing tools to show the workflow, rather than typing commands.

Transifex — Online translation service, and you can use “pip” to install transifex-client.

Tips for translating Sphinx documentation

  • Use English for all text inside code. The source code isn’t part of the translation.
  • Always use inline syntax, otherwise the URL will get lost when using aliases.
  • Maintain versioned URLs. Use extlinks extension to define URLs in the configuration.
  • Special cases — ifconfig
  • Link checking — linkcheck

What’s missing?

  • Build all languages at once.
  • Method to add a “landing page”.
  • Setting for translations.
  • Use gettext_compact to create a single catalog.
  • Language switch template.

Sphinx 1.3

  • Merge sphinx-into into Sphinx.
  • Move Transifex support from spinxh-intl to a new extension.
  • Allow to build all languages with a single command.

Write The Docs EU — Idan Gazit — Advanced Web Typography

Idan Gazit

I’m at Write The Docs EU today in Budapest and will post semi–unpolished notes from sessions throughout the day after each talk finishes.

Quote from the book Thinking, Fast and Slow by Daniel Kahneman

[…] Maximize visibility.

Micro vs. Macro

Micro:

  • Typeface
  • Kerning

Macro:

  • Measure (width)
  • Leading (spacing)
  • Flow of type on page

Books offer tons of control, while the web…not so much.

16px is the absolute size of text on the web. Relative units (1 em) are proportional and doesn’t break a layout.

“1 em” is equivalent to an uppercase “M”.

Problem with Ems: More difficult to determine the chain of relative to the HTML tag nesting and multipliers to use.

Root Ems (Rems) are much easier, relative to the root, and easier to make proportional layouts.

Typefaces

Database of Fonts (font face for browsers)

http://alistapart.com/article/say-no-to-faux-bold

The dreaded FOUT (Flash of Unstyled Text) vs. The somewhat–better FONT (Flash of No Text)

Neither are better.

Less than 3 seconds is best, but after that, you might see FOUT or FONT.

Tips:

Rabbit Holes

  • Type rendering

Rasterizers turns an outline into pixels.

  • One on OS X
  • Three on Windows GDI (Grayscale, ClearType, and DirectWrite)

Rasterizers depends on the PostScript and TrueType fonts. See “A Closer Look At Font Rendering”

Takeaway: Test your intended typefaces (everywhere, to be safe).

Ligatures: Special combinations of letters that connect.

The Four Numerals (that we really should care about)

  • Oldstyle (goes below the baseline)
  • Lining (always respects the height of a capital letter)
  • Proportional
  • Tabular (font-feature-settings, which works in most browsers)

Another cool resource: CanIUse.com

Compatibility tables for support of HTML5, CSS3, SVG and more in desktop and mobile browsers.