Unconference Session #4 Notes – TC Camp 2017

Documentation for The Internet of Things

Top takeaways:

  • We still don’t know exactly how the IOT works or will work.
  • Our end user for some information now includes the machine itself, not a human consumer.
  • We expect an increase in API docs.
  • End user docs may decrease for the human component. If there is user control, there must be user doc. May still be in different forms – i.e. virtual reality.
  • Standards are much more important, not just within your company, but across all devices you work with.

Notes

REST APIs must be involved, because it’s a dialog between technology. Processing huge amounts of data. Not sure where doc fits in – it’s machine controlled. Increases need for API doc but otherwise it’s just working. Not traditional doc but still something.

Consumer of our info is changing to the machine. We don’t know how it is going to work. Hairbrush that can analyze your hair. Scales that analyze your weight pattern. Doc for these things are for the app to get that data. Not always just the product app because it integrates with other products who should be doing that dependent doc.

Info req. Depends on device and purpose. If documenting a soil sensor may not need as much as a health care device. Dependent on a standard for all devices to talk to each other so doc needs to also evolve to conform to that standard even if all products aren’t created by you. Smart home devices have different platforms, APIs, etc. but eventually when homes talk to other homes – where’s the common ground. Does one end up winning?

If this then that – website with applets. Ifttt.com

If you go to hardware store you don’t get a manual for nails. Similarly if you buy something that talks to something else you don’t need doc.

If there is a user control, it needs doc.

Documentation Automation

Top takeaways:

  • Macros good for automation
  • Standalone tools such as AutoHotKeys
  • Tools such as Ant, Make, Powershell, and run process on the docs.
  • Excel is useful as a step in running automated processes.
  • Flare command line can be used to automate builds of Flare projects.
  • Build tools such as Jenkins to create scripts and run on the docs.
  • DITA-OT QA plugin can be used to automate QA on the docs.

Notes

  • Problem generating form Scala code. Could do Javadoc.
  • Can use macros to automate.
  • There are macro applications that work [.. ??]
  • AutoHotKey – macro create, edit, execute
  • Powershell – Windows command line, can read XML and JSON, it turns it into objects and creates an object tree. Modify into MS Office products. Can use it to auto-create PPT. Part of OS in Windows 10.
  • Python has library[?] amd can make [ ??? ] Excel file
  • Regular expressions can use to automate tasks. Lots of tool editors support it and also programming languages.
  • Excel -> Notepad++ -> Regex -> Markdown
  • Excel spreadsheet -> SQL query for database
  • ATOM plugin  generates TOC for MD files, Markdown TOC
  • Make files – simple – can save and run commands. Auto-generation after Make
  • Excel can be used because it’s structured, eg. making files from XML, used Excel to set up commands to run on on XML file (XSLT script could also be used)
  • Flare’s CLI can build your Flare project and you can get it to do some automation.
  • Can use Jenkins automated build tool and create scripts to run on docs. Maybe add parameters for diff outputs (like ZIP).
  • Can write commit tool for Git that does a certain action on a commit.
  • AZARDI – EPUB reader for desktop.
  • DITA-Open Toolkit QA plugin can input terminology and markup condition. Eg. point to set of topics, it checks for conditions and generates a report.
  • Acrolinx – tool in cloud, configure to check docs and generate a report.
  • Hemmingway app – is good for editorial comments.

Effort Estimation

Top takeaways:

  • Scope time and effort, use existing metrics from previous projects, Joanne Hackos.
  • Add sufficient fudge factor (~10%) for surprises and unknowns.
  • Educate others in company about authoring/publishing process.

Notes

  • How much time does writer(s) have? What’s absolutely necessary?
  • Use existing metrics to estimate hours. (J. Hackos seminars) Quick time, quality, cost – one or more weeks to give.
  • Schedule back from deadline, 1-2 weeks fudge factor.
  • 40 hours to produce 1-2 hours of training material
  • Use metrics from previous projects.
  • User Assistance (Joe Welinske) – little content based on user testing.
  • Why make the estimate? To get paid fairly, realistic schedule, manage resources.
  • Educate others in company about authoring/publishing process.
  • Schedule impacted by dependencies on developers/other team members, product keeps changing.
  • Freeze dates (code, UI, features) – if not adhered to, impacts schedule.

How to get users’ feedback

Scribe: Julie McMullen

Top takeaways:

  • User feedback does not equal doc review
  • User feedback can be direct (you → them) or indirect (e.g., through Support)
  • Survey is good so you can control what/how is asked
  • Analytics provide feedback indirectly (page counts, search terms, etc.)
  • User forums provide feedback

Notes

  • Users = people who user the docs
  • Survey – to mailing list for outtages, etc. – had to get approval
  • Are you even allowed to talk to customers?
  • Figure out what you need to know before creating questions
  • Results are helpful, help identify trends
  • Difference between feedback & review comments
  • Survey could fix this
  • Is it the user’s job to give you feedback, though?
  • One way is “Give Feedback” button
  • Bottom line – get feedback whenever/however you can
  • Feedback – direct or indirect
  • Analytics can give feedback

Style Guides

Leader: Elaina Cherry

Scribe: Share Clare

Top takeaways:

  1. Style guides make authoring easier. You have authority to enforce consistent wording
  2. Look & Feel belongs in a style sheet, not a style guide
  3. Style guide must address higher-order issues, that enable non-writers to contribute content

Notes

More than just Look & Feel? Yes! Look & Feel is for the style sheet

These are just a few items to be included:

  • tone, voice, tense
  • capitalization (do headings use title or sentence capitalization)
  • spelling (acceptable variations from American standard spelling)
  • terminology – also what not to use
  • rules such as headings are never followed by headings
  • principles – such as breaking content into steps, using minimalist principles
  • use of abbreviations (e.g., i.e., etc.)

What is it for?

  • Training other writers
  • Settle disputes
  • Used during reviews

Is a style guide important?

  • This topic attracted fewer people than other topics

Who is the audience for the style guide?

  • Engineers (especially non-native English speakers)
  • UX designers
  • Marketing

Getting hiring managers’ attention

Scribe: Aleida Vandenbosch

Top takeaways:

  • Take the initiative to connect with recruiter
  • Research, Research!
  • Strategies:
    • LinkedIn: portfolio sample to LinkedIn
    • Resume: skills on tap
    • Phone: narrate your exp to their needs

Notes

  • Who just updates LinkedIn and expects some recruiter to contact them?
    • No one reads every word: Keyword search. – tailor to job you want
    • LinkedIn Profile is forward looking
  • Tailored cover letter with keywords for job description; every application needs tailored cover letter
  • If not getting activity, not qualified and/or change strategy (e.g., LINKSV = profile db companies; do research, direct in mail, get on their radar).
  • How to get on radar of hiring manager – rely on networking and interact with them.
    • Make sure you be gracious, helpful, appreciate initiative, give them an option to say No.
    • Or employee-referral bonus incentive – ok to network with them too.
  • Recruiters: too many out there and inexperienced. Saturated market; new reality-recruiter may not know or talk to hiring manager. Time to fill position taking longer to fill.
  • Portfolio
    • What writing sample is in demand.
    • Make sure portfolio writing sample is linked to LinkedIn, if you don’t have time to build own website.
    • Put something on LinkedIn first – gives hiring manager reason to take seriously.
  • All companys have own self interest
    • e.g. # of social media followers – collect connections; youtube video: video skills/knowledge
  • LinkedIn status updates go to all of your connections
    • Couple times a month and only if you have something to say.
    • Ppl will tune you out if too loud and too often.
    • Keywords will help you.
  • Portfolio Samples (max 4 pg from TOC – no need to be in order – Intro, sub topic, reference).
  • Resume: Skills at top (before work experience) and include categories to show you know how to org info.
  • Job Titles: Current title is just “Technical Writer” but I feel like a Sr. Can I add that level? Yes.

Phone Job Interview:

  • Find out about recruiter and hiring manager
  • They love taking about themselves.
  • What is your idea candidate and narrate to that.
  • Research, research, research.

 

Unconference Session #3 Notes – TC Camp 2017

Tools for documenting APIs

Top Takeaways

How to choose a tool:

  • See www.indoition.com — A website on technical documentation know-how
  • OpenAPI is hot
  • Some writers “do it by hand” in Frame or similar
  • YAML — not a markup language. RAML — REST API markup language. All RAML is YAML, but not all YAML is RAML

Notes

What tools?

  • Swagger, PostMAN, RAML, Jekyll
  • Facilitator used Jekyll-based modified to use RAML
  • Readme.io — publishes on public site (considered a drawback)
  • Box, Android, GoogleMaps, Stripe, Digital Ocean,
  • Swagger (openAPI) takes JSON and makes display
  • Various home-grown tools are out
  • Jekyll is written in Ruby
  • How to do cross-references between a generated doc and expository doc (e.g., developer guide)
  • How to choose a tool?
  • Is there a survey?
  • Google API Discovery Service is similar to Swagger

Large, complex doc systems with markdown and Git

Top Takeaways

  • Top trend, especially with MS Docs; MS to Azure evolution
  • Major challenges: Search, link validation, finding files, reuse, structure
  • Most solutions involve custom programming to scale
  • Check out Ralph Squillace presentation
  • What works on a small scale probably requires more and more programming at a large scale
  • Translation is an obstacle; vendors don’t often accept markdown

Notes

  • Does it scale to a gigantic system?
  • Is this trend the future?
  • Can you apply it to different industries (machinery, pharma)?
  • What do you run into at this scale? IBM — you need a custom program
  • How to keep track of topics? Schema for adding structured metadata to find content; reuse; automation; translation
  • Why did MS make this move? Empower employees to write
  • What works on a small scale, may not scale to a larger system
  • How to you validate links? Xenu is a tool
  • Running validation scripts is huge
  • Writer using markdown is aware of potential problems with search and scale
  • One writer uses custom Ruby syntax
  • One writer wants to move to markdown to simplify

Case Studies

Top Takeaways

  • Sources: Marketing docs, Engineering docs, bug reports, field visits, Marketing, engineers, tech support
  • “I know this. Can you tell me the next step?” building a relationship with engineers
  • Ask the right questions; guiding the conversation for what is the problem and what we are trying to solve

Notes

  • This skill is important for all tech writers
  • New and returning tech writers find it difficult to gather information
  • Communicating with customers is important in gathering material
  • Users are more important than developers
  • Marketing wish list: MRD, ERD, use case scenarios give information about the product, but not the use
  • Know the user
  • Site visit good source
  • Tech writer’s role to give feedback to developers on usability to improve design
  • Quality of raw material is important; if raw material isn’t of good quality, ask questions
  • If using MRD, QA and tech support are a good source of raw material
  • Bug reports

Creating a Documentation Delivery Platform

Top Takeaways

  • Get buy-in and support from multiple teams
  • Workflow to determine tool instead of vice versa
  • Trade offs for custom-built vs. out-of-the-box solution
  • OK to use many tools and customizations
  • No one right solution

Notes

Skills: XSSLI, HTML, CSS, design, getting from source to output

Creating requirements, project management, get buy-in

Development buy-in handy to really get support involved and integrate their requirements

Single domain search

Team ownership: different views, different stakes

In what instance should you do HTML or out-of-the-box solutions?

  • Tools are expensive and require implementation and customization
  • Want to look unique
  • Is the tool over built?
  • You don’t get fixes
  • Must maintain customization

Public vs. Private: depends on content

What tools are people using?

  • Mediawiki: Great publishing tool. Accepts HTML and wiki text. Open source and free development extensions

Tool process:

  • DITA->OxYGen->Git->DITA Open Toolkit->HTML/JSON->support portal->Swift-type->Docs

Tailor things to your internal process

Use Google Docs for collaboration; go to markdown, and then HTML

Workflow more important than having a custom tool

Output:

  • Who wants PDF?
  • XML
  • HTML5
  • epub
  • What devices are people using?
  • Research format

Markdown handy for code review

Localization issues

Session cancelled. No notes.

DITA vs Markdown

Top Takeaways

  • No “vs.” it’s a different use case
  • Reuse/conditional text, mapping topics, semantic tagging
  • Large topics unmanageable in markdown
  • Markdown is great for simple authoring and formatting small topics
  • Markdown popular with developers
  • Interest and amount of activity in SourceForge, and markdown capabilities.
  • DITA needs simpler tools to market to SMEs/developers

Notes

Tom Johnson: Developers like markdown; kind of like a text editor with some tagging.

Markdown:

  • popular with people who don’t use DITA
  • Format but no reuse or conditional text
  • Purely for formatting simple text — very simple
  • Simple conversion, usually to HTML

DITA:

  • Criticized for complexity — developers don’t want to use DITA

Markdown so popular, many DITA tools convert it

What can tech writers learn from simplicity of markdown and its popularity?

  • Internal software API — markdown is DEV & QA -> endpoint internal wiki, website
  • Complex use cases will fail: cross links, cross references likely to fail

Markdown source compatible with features like HTML tables, but cumbersome

Consider markdown a tool for SME/DEV

Contributors consider markdown a “young person’s” (millennials) tool

Is there a future if the key players for DITA are gone?

Do we need to produce large document sets?

Better to think of end product, and see what tool fits

Open source and markdown is hot

Key Features Comparison

  • Arrangement/mapping:  DITA (2) Markdown (1)
  • Topic typing: DITA (2) Markdown (0)
  • Basic revisions: DITA (2) Markdown (1)
  • Metadata: DITA (2) Markdown (2)
  • Semantic tagging: DITA (2) Markdown (0)

Unconference Session #2 Notes – TC Camp 2017

#1 MarkDown for Tech Comm

Scribe: Lynn Cooley

Top Takeaways

  • It is reasonable to use MarkDown for docs depending…
  • If you need re-use or conditional text, try asci doctor.
  • If you need fancy formatting, put HTML into your MD doc.
  • Converting MD to other output formats works with tools like pandoc, but the reverse direction can lose some formatting
  • One writer has done a 40,000 words doc in MD as a web doc.

#2: Tech Comm in an Agile Environment

Scribe: Loria Kutch

Top Takeaways

  • Agile is about figuring out what you can do, not how.
  • If you are not on a cross-functional scrum team, you’re not really doing Agile.
  • Agile means different things depending on who you ask…despite the Agile manifesto.
  • Succeed or fail as a team, no bottleneck blame.

Notes

  • Pros: being in sync, story for back and front makes it easier, doc task in scrum
  • Cons: iterations, definition of done can change without QA
  • Pro: engagement of the scrum team
  • Con: many scrum teams
  • Pro: Build respect of writers/product owner, scrum master. Can add doc review task.
  • Con: feature driven can get away from user tasks
  • Con/Pro: can feel too structured, but the structure can be nice and visibility/transparency
  • Kanban vs. scrum… doc-wise Kanban visual, personal-wise scrum
  • JIRA’s not snooping.
  • Asana, Google groups, trella, failures
  • Failure: major features at the end (like waterfall). Two teams had failure issues at the end of the cycle.
  • User feedback along the way.
  • 5 years to get to efficiency
  • Cross-functional scrum teams
  • QA and docs shouldn’t be last, need the flexibility to move the tasks.
  • Agile doesn’t really mean faster…just iterative, customer viable, self-managing, success or failure as a team.
  • Using “agile” to manage “waterfall” but without using the tools like retrospective and stuff
  • The goal of agile is different depending on who you ask.

#3: Improving Search in Technical Content

Scribe: Elaina Cherry

Top Takeaways

  • Getting rid of old topics/content can improve results
  • Pick-lists of approved terms (tags, taxonomy)
  • Have support point out the doc portal at end of conversations
  • Analytics! Search Logs! Review them to inform terms/tags
  • Subject Schemes

Notes

  • Do ppl search your site, or google?
  • Offering metadata filters
  • Synonymous key words, tagging
  • Sometimes adding metadata is too time-intensive, gets abandoned
  • Reviewing search logs can help spot issues (monthly)
  • Track page news, page visit length
  • Internal vs. external users have different search needs?
  • IBM Watson search-learning
  • Tagging content for internal users? Use alternate titles for searching. “Search alt “title”
  • Separate team that handles SEO?

#4:  Career Paths out of Tech Writing

Description:

  • The tired tech writer is no myth. Many who got into the profession during the internet boom years remain only to pay the bills, not because they still hope to make a difference or even find work they enjoy.
  • Let’s explore the pros and cons of alternative professions. What’s your preferred path up and out?
  • From the typical options (project management, training, instructional design, content writing, content strategy, UX) to more esoteric ones (localization, medical writing, product management, software development, recruiting, even life coaching), you have choices. Come learn from your peers about how, when, and why (or why not) to make the leap.

Scribe: Nathaniel Lim

Takeaways:

  • Tech writing is a broad term and a broad profession
  • Tech writers do many different jobs
  • Narrow your niche (e.g., tech writing, ux design, instructional design, etc.)
  • Shed the term of “documentation” from your title
  • Find what you are good at and cross it with what you love to do
  • Find a company’s pain points and solve their problems
  • Do a lot of networking
  • Reinvent yourself
  • Go to Meetups
  • Go to Expos and conferences

Notes:

  • One person worked for a company that did UX before it’s time. Since they worked for other companies that wanted her to do tech writing only and got other people to do UX design. Now wondering if she wants to move on from old fashioned tech writing
  • Tech writing has changed so much in last 30 years. Tech writers are doing multiple jobs. Used to be separate: writing, illustrations, editing, photos, etc. Moved on from tech writing to documentation consultant for companies that need information security, government compliance writing, Leverage background and experience from writing for various companies
  • Information Architect is today’s term for tech writing who can plan documents. Most companies do not hire an IA until it’s too late. Recommend getting into a high tech start up so it’s not too late
  • Get your foot in the door and reinvent/create your own Network. Shed the “documentation” title. Pick a narrow niche (e.g., tech writing, ux design, instructional design, etc.)
  • Cross between what you are good at and what you love to do
  • Go to conference expo halls where you get in for free. Pick up all their literature and look for typos. Write to them and introduce yourself pointing out the typos. Find their pain points and tell them how you can help them
  • Tech writing -> web design -> database management
  • Clinical forms designer -> tech writer
  • Technical book reviewing
  • Technical training pays well but requires travel
    • Info architect good pay but gets laid off easily
    • UX designers higher pay
    • Life coaching (pays lower)
    • Recruiting (pays lower)
    • Tech illustrators (pays low, tends to be freelance unless you have loyal clients)
  • Meetups & Networking

#5: Best Practices for Document (Left Side) Navigation (web)

Description:

  • What best practices exist for documentation navigation?
  • Should you implement progressive disclosure?
  • How many levels before users tear their hair out?
  • Do users even look at the sidebar?
  • What are some examples of navigation sidebars that succeed and fail?
  • Should you eliminate the navigation altogether?

Scribe: Liz Miller

Takeaways:

  • You need the hierarchy & teaching value of the TOC, Left Nav or high level overview
  • Plan for search-centric users who enter from google while possibly distracting inline links are good optional clicks.  (Ignore or open in new tab so as not to lose your place)
  • The Indexing skill & Indexes are obsolete due to Google/search trends however metadata tags allow SEO, custom audience-centric views
  • Animation catches eye, direct nav (clippy, gif..)
  • When all else fails, press Ctrl-F

Notes:

  • Nav index, xref, keywords, quicklinks -> User Nav Help
  • At a glance overview can link to doc sets vs expanding three levels
  • Limit volume of options, use hierarchical drill-down for detail (note first level) also serve Google discover entry to site: breadcrumbs, paths
  • Use Google Analytics to see search/entry (vs LH Nav) patterns.
  • Bottom Up Nav vs Top Down Nav = better for search-centric approach
  • TOC hierarchy has contextual value (TOC as teaching tool, index too)
  • Google search predominates today; results title should apply to all (not chapter)
  • Inline links get people lost; go back in PDF is not a good option
  • DITA db topics tiny but many are rich and long
  • Beware DITA effect: too many tiny topics and a TOC that is too large
  • Chunking of content long or short?
  • Overlays?  Inline links, index, glossaries, faceted search, tags, cross-links
  • Too many validations?
  • Index = synonyms, links, metadata
  • Search as a primary means of Nav
  • Are users even using the sidebar?

#6: Content reuse mechanisms in DITA

Description:

  • A big selling point for DITA is content reuse/single sourcing. Managers look at reuse as a means to justify migration to DITA.
  • What are the different ways to reuse content in DITA, how is it done mechanically (conrefs, keys, etc) and how successful was it?
  • How do you measure the reuse (for example, this topic is now used in 5 books)?

Scribe: Frank Kelly

Takeaways:

  • We want the idea of PDF documents to go away or writing for PDF to go away
  • DITA may or may not work for recipes
  • Common reuse: conref, refs, scop keys (investigate scope keys)
  • Topic level reuse saves you significantly on translation
  • Copy and paste is the common reuse mechanism

Notes:

  • Want to see PDFs go away
  • Cross document linking because the guide grew too large, no experience
  • Forget the term document, let’s call them buckets to help us understand better
  • We are trying to find out the use case and benefit of scope keys in DITA 1.3
  • Default is included, ditaval excludes, counter intuitive
  • Keys for resolving product names, overhead for conref range
  • Relationship tables
  • Output to HTML, cross-departments
  • Techcomm is rooted in customer advocacy