Unconference Session #3 Notes – TC Camp 2016

Documentation workflows based on Markdown and GIT

Scribe: Matt Ness

Top Takeaways: 

  • GIT and Markdown go together; GIT uses text files and opens in Markdown by default
  • Writing documents in GIT enables you to use the same content workflow as your engineers
  • Markup does not enable the same amount of formatting capability as other authoring tools, though you can augment it with HTML
  • Good editors- Notepad++, SublimeText, Atom, MarkdownPad

Notes: 

  • Kamodo- have good markdown support
  • Markdown is a markup language- how is it implemented. One of a family of text based languages- intended to be easy to use. The markdown site gives you a WSYSIB view of your output.
  • Scribe has contract job where he was asked to use XMGTAL, but this is not good for his project, Markdown advantage; used to let developers into GIT. Not as flexible as Word or Framemaker w/r/t styles and formatting. Markdown is like simple HTML.
  • Markdown may be too simple say some.
  • Discussion of formatting-you can do a lot with its basic markup and then add HTML for advanced formatting.
  • Pandec is a good markdown- HTML converter is very scrib similar with markup.
  • You do not need to add HTML/CSS to it, would look like HTML 3.
  • Sequence is CSS does not apply until markdown is converted to HTML.
  • Chrome extension to view markdown
  • Markdownpad- view/edit markdown files
  • How do you generate markdown structure
  • GIT- using for documentation- Use to monitor changes to documentation and track changes
  • Discussion of GIT workshops- all internal communication are managed through GIT
  • These are organizational issues, not technical issues. GIT respositories use Markdown by default.
  • When you do your pull requests- same as source code- the doc reviews.

Localization

Description: 

  • Writing for it, publishing it, managing localized content, process engineering, best practices

Scribe: Alan House

Top Takeaways: 

  • Preparing your conduct- Acronyms is ideal, other “checking” mechanisms exist
  • Localization- local acceptance is important- GIGO
  • Human workflows are still best
  • Make sure you own the TM
  • Machine translation is you have training data

Notes: 

  • How to prepare your context for localization?
  • Some LSPs will localize screen shots

Metadata and Categorization strategies for technical writers

Scribe: Shari Clare

Top Takeaways: 

  • Mindmapping can help define content structure
  • Once you have the correct structure, content can be moved to be correct document type
  • Metadata is useful for: metrics, governance (where content can be used), finding information faster, getting more information of what something is, “Is-ness”- the difference of what something is

Notes: 

  • Google is a mindmapping tool, which helps you figure out the structure so you can put content into the right document
  • Reuse of content is one of the goals
  • Standards can be used as categories to help identify parts of data, which can be put together or to a whole document
  • Mental structure analogy is like Amazon, which lists topics, then drills down into a variety of categorie
  • Taxonomy falls under the field of information architecture
  • Smartlogic is a tool for managing tazonomies

Introduction to Data Modeling: How to Start Thinking About Reuse

Scribe: Guy K. Haas

Top Takeaways: 

  • Understand the problem- what elements are constant in repetition, and what are variable
  • In your tool, determine what functionality(variable,conditional, snippet or text inset) to use
  • Data modeling has a long ramp- up time when it comes to re-use. Rules for naming, categorizing, etc. But it pays off at translation time

Notes: 

  • Governance processes might be necessary depending of scope of project. If someone else might take it ever, or if multiple authors are involved– need to document the logic of the reuse
  • Some tools are better than others at supporting governance
  • Need management of governance
  • Establish the atomocity of reuse
  • If a topic has more than 20% of its content as reused material, split it.

Leveraging LinkedIn

Description: 

  • Leveraging LinkedIn to get yourself noticed. Since Andrew spoke last January, they’ve totally transformed the UI and many of the features, so even someone who attented last year will get value from the presentation.

Scribe: Peter Jew

Notes: 

  • Any power wars? Moderate. Try to update regularly so they won’t forget.
    Too much update- recruiter gets triggered and get calls
  • In mind is one advantage, but it has become very hovey.
  • Sometimes you get someone who already connected with
  • Get recommendations and references
  • Get consistent references- you can edit and work with the recommendations
  • Best way to get a recommendation is to ask the person to recommend yo and tell them what you wanted to be.
  • You should also rejuvenate
  • Goggle search- add “tech writer”
  • Most recruiter will go to LinkedIn first before they post a job
  • You can restate the skills last at the bottom
  • If a recruiter contracts you, respond even if you don’t need a job.
  • Other people may mind your network and connections- you can set visibility on connections
  • Add photo
  • Keep your resume more detail and specific to the job- LinkedIn should be genuine and lots of keywords
  • Join LinkedIn groups and keep abreast of head
  • When browsing for jobs- stay obscure if desired
  • Premium gets directed email and advanced search
  • Job seekers may get premium and get to the top of the list
  • You can contract recruiters via twitter

Writing/Formatting Best Practices

Description: 

  • Standards as they apply to the technical writing profession, process, and data items.

Scribe: Karl L. Leader: Bonnie

Top Takeaways: 

  • Depends on context, audience, etc. “Never any absolutes.”
  • Semantic markup lets device and style sheets determine look and format, using some tag and each case.
  • Best practice for typography may not be same as tech writing
  • Automate formatting
  • All differences have to be “neat”, be consistent as much as possible. Not arbitrary inconsistency- (yet maybe appropriate with informal tone)

Notes:

  • Proposal: 2 levels of headers, level 3 gets blurry.
  • Scemantic tagging= fonts/formats imply meaning. Made with code “what it is” not represents, emphasithes. Categories
  • If topics maybe heirararcal or equal depending on context.
  • Use a minimal number of headers, no more than necessary
  • Conceptualize device format “large vs small” not “mobile vs desktop”
  • Have a style guide and use it! Different devices have new action verbs. Eg. “cick” vs. “tap”. Write specific to device or more generic terms like “select”.
  • Research= Trend m mobile.(Apple uses no numbers)
  • Steps in procedure do not have to be numbered.
  • Priority is to fit content on smaller screens rather than numbered list. But very technical does benefit from if steps.
  • Strong based tutorial,no numbers.
  • Move to casual tone of voice- moving to allow contractions- even in LBM style guide R MS style guide
  • (Advertising seldom was complete sentences)
  • People jump to images, sleep text blocks
  • (A lot of tech writing rules are based on research)
  • IEEE professional communicators publishes academic journal.
  • How many have done usability testing of content.

 

Workshop Notes – TC Camp 2016

Content Strategy

Scribe: Amy Bowman

Top Takeaways

  • Traditional tech writing (concept, task, reference) is not dead-just delivered differently.
  • Make content engaging, entertaining, and experience.
  • Type and Content-discover, learn, do
  • Make writers content strategists-give them the vision let them decide how to meet it-what’s best for your own content?
  • Notes

Salesforce-“Doc is dead”

People introducing themselves and what their challenges are in the area of content strategy. Four of people seem to be moving from traditional doc to more modern doc at the request of their management. Content teams are misaligned and could be misrepresenting the brand. Docs should focus on “when to and why to” not just how to. Content experience-reflects on the brand. Interactive and gamified content-gold star effect. Strat w/UI text. Help only for things you can’t explain easily in UI or walkthrough. Complement with video, ?????????? Progressive discovery-iceberg-provide content in progressively more detailed chunks.

Git

Presenters: Jamie, Jen, Stefan, Training.github.com

Scribe: Bonnie Kim

Top Takeaways

  1. Create Branch.
  2. Add commits.
  3. Open Pull Requests.
  4. Discuss and review.
  5. Merge and Deploy.
  • Git hub can be customized for your workflow!
  • Gihub is useful for version control and record keeping.
  • Work off of local copy and branch. NEVER off of master.
  • You can work off of website, desktop client, or command line.

Notes

Working primarily off of github.com-friendly user interface. Traditional workflow is tech writing workflow.

“Understanding github flow”

  1. Create repository.
  2. Create branch.
  3. Add commits.
  4. Open Pull Requests.
  5. Discuss and review code changes.
  6. Deploy! (squirrel)

Github tech writing workflow

2 repositories:

  1. Doc strategies.
  2. Help docs repository → issues

Tickets → push to docs. Very descriptive branch names. Atom text editor. Commit often (pull request ASAP). 1 commit per change (200 per round) local changes → web PR pull request “close issue #s” w/key words Mega branches → accumulates changes across multiple smaller branches organizational tool (best practice branch management NEVER WORK OFF MASTER – ALWAYS WORK OFF BRANCH → DEPLOYED STATE → PUBLISHED

Git is designed to make branching EASY!

Pull request; push request → requiring higher-level approval G tech writers (including managers) for 400. Make changes and push changes LOCALLY. Then deploy or be very descriptive of hat changes you made per commit. Liquid Syntax → markup language by shopify → used in Jekyll (for high end use).

Non-pretext software version control gets tricky Access for developers and new writers-advantage of plan text file. Even if GITHUB goes down… Everyone has local branches command line access is encouraged, but web- and cs-clients are available for easier user-access.

Feature or document branches-per separate unit before you start work → do GIT pull Fetch → step before pull to recap change history → compare local repository w/master (TRUST) Pandoc → converter HTML → Markdown (3rd party) w/manual checks Pure markdown for simplification

Recommend creating ReadMe populated with IMPORTANT INFO for users, contributors, etc. – project info of notes issues → Bug; suggested fix → labels, milestones, assignees → ready for review, SSH (topic), etc

Collaboration requires extending and granular communication mention users teams, etc.; keeps records of everything start now!

Park, and open pull request.

Keeping Yourself Marketable

Scribe: Karen Aidi

Top Takeaways

  • Roles for technical writers are unequal.
  • Most valued to least valued roles:
    • Most valued: Developer Doc
    • Less valued: End-user, system admin doc
    • Least valued: internal procedures or compliance documentation
  • Sectors for technical writers are unequal.
  • Hot: mobile, big data analytics, saas/virtualization cloud, security, open source
  • Lukewarm: enterprise, medical devices

Notes

  • This is a huge topic and Andrew could not cover it all in two and a half hours. If you want to find out more information for example, on how to present yourself on your resume, see Andrew’s website: www.synergistech.com.

What is the market like? It’s:

  • Cost containment is job#1.
  • Hybrid roles are prevalent.
  • No training available. Carrot and stick leadership. Greed, fear, and layoffs.

Locations are unequal:

  • Hot: San Francisco
  • Cold: Santa Cruz
  • Lukewarm: South Bay

Finding Opportunities

  • Networking is still the best way to get a job. Getting a referral matters. For off the radar opportunities, go to:
  • LINK SV: www.linksv.com (discover off the radar listings)
  • LINK UP: www.linkup.com (current, under-publicized listings)

Training

  • Be prepared for your job interview.
  • Understand the technical domain by exploring online training:
  • Code year
  • com
  • com
  • com

Interviews

  • Go to Andrew’s website for interview tips.
  • Arrive rested, well-informed, and armed with lots of questions.

Negotiations

  • Determine how much you need to live on.
  • If you contract, check out ???????.com

UI/UX Writing

Scribe: Joanne Grey

Top Takeaways

  • Think end-to-end: new user/first we-ongoing-deeper understanding
  • Early integration is key.
  • Measure success/problems with good metrics
  • Consistency instills customer confidence and trust.
  • Patterns create consistence. Develop a pattern library.
  • Patterns let customers think less.
  • Voice conveys who we are and our relationships with the hearer.
  • Tone conveys the situation and emotion (lead the way, keep it simple, be upbeat).
  • Make sure tone is appropriate.
  • Voice and tone adds value, metrics can confirm.

Notes

  • Long metrics matter: reality check, areas for improvement, plan resource use and manage up.
  • Keep team excited, settle disagreements.
  • Use feedback during process is important.
  • Consistency across UI/UX provides clarity, instills user confidence and trust.
  • Share your style guide across the team. Guidelines for mobile, global, abbreviations.
  • These guides can become the basis for patterns.
  • Patterns provide a common language across the team.
  • Attendee observation: There is no such thing as “intuitive” only “familiar”.
  • Patterns and styles are always evolving. They let the team learn from each other’s work. Patterns help globalization.
  • Voice is consistent but tone can change. Voice says who we are and define our relationship. It’s your personality. Tone is relevant to the current situation.
  • Read content out loud. Watch for positive/negative feedback, collect and document examples. Add voice and tone guidelines to style guide.
  • What do you want to get out of this? Mobile use, globalization, orienting, learn more, UX designer not equal to UX writer., web content interest, how to talk to eng, methodologies.
  • Adding value through consistency and patterns.
  • Voice and tone (and emotions in between).

Unconference Session #2 Notes – TC Camp 2016

Documenting APIs

Description:

  • Documenting APIs

Scribe: Todd Lewandowski

Top Takeaways:

  • API Docs are “hot”
  • Necessary to have a programming background, however small. As much as you can!
  • Lots of free resumes online & through library to learn coding
  • Deep guide for all functions (references)
  • How To Guide for tutorials, Getting Started (concepts)

Notes:

  • API Docs is “hot”. Good for job future. Easier to transition if came from programming background. People have large codebases, now they’re ready to make them work together.
  • What is the tipping point where and API doc is necessary?
  • wait until problems appear
  • when communication really REALLY breaks down
  • esp training[?] for new lives[?]
  • show value now for future growth
  • Tom Johnson (free course)
  • JavaScript & Python – two best to start
  • Programming skills are super helpful (at any level & any language). Though your particular project varies.
  • Codecademy, Santa Clara/SF/San Mateo library card access then access to online repositories.
  • What are good or bad examples of API doc?
  • Swagger (tool) for REST APIs, or RAML – to make specifications in a good format.
  • Deep side w/ parameters, variables, etc. (references)
  • How To Guide w/ tutorials (concepts), Getting Started, examples
  • SOAP APIs

Jobs

Description:

  • Job searches.
  • How to break into a new industry.
  • Hot markets: looking outside the techdoc box.
  • Portfolios – how to construct them, best practices, strategies for wowing recruiters.

Scribe: Tonie Flores

Notes:

  • Ping Pong – Hiring mgr fears you’re a flight risk.
  • They know recovery is slow, state all the things you’ve learned, put manager recommendations on LinkedIn.
  • Against non-existent no one wants to do our work. It’s hard.
  • Kids don’t know what it is. People hate to write.
  • (Dot bomb 80% loss of jobs.) for recession, tattoo on our back, Rather than let jr. developer go, Sr. tech writer goes.
  • Google – must work onsite.
  • “I can learn that” ends interview.
  • Talk geek with them. Otherwise, scares them
  • “You need to know more about their technology than they do about what you do.” — andrew
  • Call their bluff – “this is how I served that problem.” or “You called me for an interview, I
    must have some of what you want, here’s what I can do for you in 30 days, 30 days, 90 days.” don’t just apologize and cave.
  • Scratch a frontier, eg. open source.
  • Sells doc & training. Software is free.
  • Trend toward contract is hire. They are finite and infinitely renewable. Try & buy model.
  • Compensation 1099 – 45-50, Salary 95-100 med devices
  • Developer < 65 staff 120-135 geekiest of geeks.
  • Company cost 22% employer costs to client.
  • W2 can pay benefits pre-tax – vacation, medical, 401K
  • Get paid faster, can file for unemployment, 1099 – Large companies won’t, small companies do. Audit bait.
  • Monster: pitfalls – vendor mgmt systems, field glass
  • Vendor owns you for 6 months, company wide any job

How to integrate “sustainability” thinking into your work

Description:

  • Learning to ask questions about how sustainable a product or technology is, in parallel ways that we have learned to ask how usable a product or technology is, is an upcoming “need to know” skill.
  • Applying technical communication skills for sustainable purposes – where is there a need?
  • Many companies now have “green teams,” “sustainability initiatives,” and “corporate social responsibility (CSR)” departments. Some companies focus on developing products that help people and companies be more sustainable in one or more ways. All of these need people with technical communication skills, although they may not think of it as needing a “technical writer.”

Scribe: Adam P. Hunt

Top Takeaways

  • What can you do?
  • What does it mean for people?
  • Solutions. How does sustainability become normal?
  • Research “triple bottom line” business practices.
  • Ask product managers about product lifespan.
  • Make sustainability normal.
  • Ways to get involved. 360.org, Nerds for Nature, Cradle to Cradle certification
  • Just ask.

Notes:

  • Linda Urban, speaker.
  • Making sustainability relevant to the tech and tech writer community.
  • How to make a more sustainable workspace, product, and planet by both business decisions and personal choices.
  • Sustainability as product differentiation, energy consumption, and recycling efforts at the workspace.

Teaching traditional writers to write topic-based

Description

  • What is the most efficient way to teach a traditional writer how to write topic-based content?

Scribe: Liane Takahashi

Top Takeaways:

  • Provide overview, introduce paradigm, high-level why’s
  • Define topic types
  • Provide samples, examples; demonstrate improved usability
  • Define information types

Notes:

  • Define “Topic-based”, “Traditional”
  • Format vs. Content
  • Typewriter -> DTP -> content-only
  • Academic view of writing (persuasion, reference)
  • Customer-based: customer needs to know now
  • Topic-based is bare necessities immediate application Every page is page 1: search engine point of entry
  • Concepts, reference, tasks can be integrated in different ways
  • Trad. docs can still be built from topics
  • Trad. method: One author owns a book
  • Topic-based: parts of books are owned
  • Complicated procedures cannot be broken into separate topics although same sub procedures could be reused in other procedures
  • Only topic-level without transitions is choppy
  • Reference guide writing is good model for topics
  • Chunk tasks: long docs are harder to read through
  • Book: “Every page is page one” by Mark Baker
  • What is it wiki based?
  • Scope
  • Practical apps
  • Use cases
  • Value
  • How big is a topic
  • Readability, no “walls of text”
  • Depends on user and what you want to achieve
  • Non-tech writers tend towards narrative, arguments

Style Guides

Description:

  • Style guides – more than just look and feel.
  • Style guides – what goes in it and how to look at your docs to create one.

Scribe: Cheryl Hunt

Top Takeaways:

  • Style guides can encompass much:
    • Entire doc structure
    • Formatting
    • Visual elements
    • Typography
    • Wording
    • Dictionary
  • Many style guides available online including Microsoft, Apple, IBM, Yahoo
  • Some apps that can enforce word style are Acrolinx & Hemmingway
  • FrameMaker can enforce visual styles
  • Some that enforce structure are templates, XML
  • Best method of custom – style author, small committee w/ moderator and iterations

Notes:

  • Consistent look, feel & voice very important to look professional.
  • Talk to SalesForce to find out more on styles for video
  • Include examples in style guide of when the pattern should be used.

Elevate content initiatives across the enterprise

Description:

How to elevate content initiatives across the enterprise

Discuss best practices to elevate content initiatives across an enterprise and the various tools and strategies that illustrate the value of content initiatives; align to broader corporate-wide strategic initiatives; identify and track key stakeholders and their spheres of influence; and how to go about enrolling people.

Scribe: Greg Urban

Top Takeaways:

  • Need to get buy-in with stakeholders
  • Need to have consistency with usage of content with other users of the content.
  • Follow the money – content usage needs to increase and support sales. Can garner support for your content initiatives.
  • Persuasive sentence – “My job is to showcase your work” (get buyin) Get your peers to be ware of the problem. Have a bunch of people agree that a certain issue is a problem.
  • Use buzzwords – “User experience” and point out you need users

Notes:

  • Creating social media forum posts
  • Small articles / forum posts
  • Align with marketing – align with needs for deliverables from other departments.
  • Consistency – working – usability testing