Session 2 Notes – TC Camp 2018

#1 API documentation practices

Description:

  • Many of us will be coming from the API documentation workshop the previous day. Let’s have a session to discuss and share what we learned.

Scribe: Margaret Spell

Top Takeaways:

Notes:

  • Session to discuss what we learned in the API doc session. Suggestion on how to come up with info on what to do next—follow up from class yesterday.
  • Code samples under source control? AWL(?), Swagger.
  • Question on whether API doc can be automated when code is changed?
  • Also comment on setting up documentation server for API docs. How would it be maintained in consideration of different versions? Build version in URL to handle version. Interest in automation of API docs in general, automation tools also. Even programmers need good documentation experience. If we do the API docs well, we bring more value. API docs is a high-demand area. Can be complex and an area when can try to simplify. API docs constantly changing.
  • Testing APIs
  • Regarding Swagger, if the doc is interactive, is all content in secure database?
  • May have been point of confusion from class yesterday. Concern is about having the documentation on a web site. Usually have an API key that applies only to your data. Need to consider how to allow users to test API. Set up test account and let users test in a test account so they don’t mess up their data while testing. Need a server or protections on the server for this purpose.
  • API explorer = try it out. Plug in values and get response.
  • Compared to hand crafted SOK on …. they equivalent.
  • Automation
  • Thinking of how to create whole API doc solution
  • Swagger- put some static site generator. Other tricks into this? Suggest API explorer
  • Need an example to explain a more complex transaction. This is an area where more info would be good—the tools and techniques. Ask customers for examples of how they have used the software.
  • Kind of a recipe. Can the entire sequence of API calls be automated? Then API Explorer could be built in as part of this process.
  • Tools to help with construction of API docs.
  • Postman is a way to construct a template of values you set up. Explore Postman as a getting-started tool. Swagger takes experience. With Postman collection, you can save changes.
  • Challenge with understanding API docs is the language. Assumes a lot of programming knowledge.
  • “Write the Docs” podcast with Postman founder. Can have a Pro.
  • Engineers write collection, then use Publish option to build out the information. Can set up an environment with Postman.
  • Postman can auto-generate in different languages: Java, etc. Postman founder says users like this.
  • SOK is flip side of API component. That is part that is language specific. Brings libraries together to construct calls to API. SDK contains tools and documentation.
  • Challenge with API doc—if you have to document for multiple languages, use different SDKs.
  • APImatic – another tool for stuff related to APIs. Can use to convert from language to language, automate unit testing, etc

#2 Cyber security and the role of documentation

Description:

  • One reason that cybersecurity is challenging is the complexity of the conversations about it in every area of society. Explaining things simply is complicated. Technical communicators have made complex information accessible to other fields. How can technical communicators apply skills that we already have to champion global cybersecurity?

Scribe: Hannah Wiltbank

Top Takeaways:

  • Take the time to read the books and learn the acronyms.
  • There’s a good market, but it helps to have some awareness of the applicable standards.

Notes:

  • Any pharmacy has to be HIPAA.
  • Policies: high level (“we have a strict password standard.”)
  • Standards: “everyone must have a strong password, not stored anywhere, changed every 6 months.”
  • Procedures: how to change your password.
  • May also need to write about physical security, network security, or app security.
  • Government facilities use a different layer stack than commercial.
  • New European standards for breaches: GDPR. European auditors are called registrars. Audits are called surveillance.
  • CISO: corporate information security officer
  • General emergency preparedness also includes preparation for IT and security-related emergencies.
  • HIPAA requires a business continuity plan, an emergency preparedness plan, and a disaster recovery plan.
  • If you are aware of data security best practices, you can be a great asset as a tech writer.
  • CISSP: certified information security services professional. Sources differ on how useful the certification is, but it has potential to increase your salary.
  • If you attend security conferences, you become known within the security industry.
  • SP800-53 is the NISTs general security standard.
  • NIST is under FISMA: federal information security management authority.
  • You can attend the RSA conference for free.
  • For security projects, you often must work on site and on their computer.

#3 Video/Audio – When are they better than print?

Description: 

  • NONE

Scribe: Laurie d’Armien

Top Takeaways:

  • Audio is more important than video
  • Videos are great for context
  • Strike(??) out text

Notes:

  • Screencasting
  • Video of(?) human factor verbal
  • Record little videos and merge or long and snip.
  • Apple video showing movie are in addition to words.
  • Generic words, contextual video.
  • First video?
  • First audio? Do long audio
  • Audacity open source

#4 Freelancing

Description:

  • How to freelance as a Technical Writer in the Bay Area. Finding clients; customers; pain points; How much to charge; Tips/advice, etc…
  • Business setup: through agency or sole proprietorship/LLC
  • On-site vs remote

Scribe: Iris Rodgers

Top Takeaways:

  • When you’re freelancing, you’ll have to sell yourself – find places to show your work and network extensively.
  • Sell the quality of your work over the quantity. Don’t see what you do, sell that you solve problems.

Notes:

  • Why do you (participants) freelance or want to freelance?
    • Has done before
    • Likes the variety and flexibility
    • Is an experienced tech person, “you don’t need to hold my hand”
    • Freelancing makes economic/business sense
    • Opportunities to learn new technologies
  • Sell the quality of your work over the quantity
  • Big companies will want freelancers to go, agencies vary between 1099 and W2 work. Small companies tend toward 1099.
  • Finding clients:
    • LinkedIn Pro
    • Company posts
    • RFQs
    • FlexJobs.com
    • Remote.com
    • Networking (This option can be slow – need to be persistent with your contacts)
    • Glassdoor.com
    • Indeed.com
    • Direct relationship with hiring managers
    • Staffing agencies (comes with pros and cons of using a “middle man”)
  • How much to charge?
    • 80k/year on a W2
    • 160k/year as 1099, but this is a maximum
    • You’re working 2000 hours, get paid for it.
  • Freelancers, you are your own salesman and hiring manager.
  • Don’t sell what you do, sell that you solve problems.
    • Ask what the problem is or what the pain point is
    • Address that problem.
    • Be proactive.
    • This is how you’ll get to a hiring manager before they even post the job.
  • How do you estimate work?
    • How long is the document
      • Rule of thumb: 1 page = 1 day
    • Scope of work is often underestimated by the manager, so you’ll have to walk the line between real estimation versus the estimation that gets you the job.
      • You’ll need to gauge how realistic the particular manager is.
  • Advertising Methods (Getting Work)
    • Write articles on LinkedIn
  • On-site versus remote
    • Remote work is harder to get than on-site
    • Freelancers often do both.

#5 DITA, lightweight DITA, and markdown

Description:

  • Can Markdown replace DITA (or other structured models) in techcomm?
  • What problems in DITA does Markdown solve?
  • What about Lightweight DITA, is that better or worse?
  • LwDITA provides for Markdown and HTLML “flavors,” will you use those?
  • Or, is this all just more craziness?

Scribe: Elaina C.

Top Takeaways:

  • DITA/Markdown are not mutually exclusive.
  • Use them all to your benefit, and find ways to convert content (e.g. so you can let engineers keep using Markdown)
  • Lightweight DITA will be a codified standard soon, and will only include about 40 content objects.

Notes:

  • Who’s using DITA vs. Markdown?
  • Lots of DITA novices.
  • DITA is more semantically structured than Markdown.
  • Markdown has minimal structure, i.e. paragraph, list, but not “prerequisite paragraph” vs. “context paragraph.”
  • <menu item>Settings</menu>
  • Ex: Adding semantic tags like ‘command’ and ‘expected output’ which later allows Python script to execute commands, compared against expected output, and verify whether the documentation is correct.
  • You can inject some structure into Markdown docs, but it complicates it so you are starting to mimic XML.
  • Advantage of Markdown is that engineers use it, it’s compatible with github and their process.
  • What’s Lightweight DITA for and all about?
  • Problem: Engineers want to contibute with Markdown, TWs want to work with DITA.
  • Lightweight DITA keeps only the minimum amount of semantic structure necessary. Not yet a fully baked standard!
  • What are the common structures betweeen:
    • Marketing procedures
    • Tech Writers in engineer land
    • Training teams
  • Publishing tool would be able to output from any of your rouses (Markdown, XML, etc.)
  • *No audio/video tags for DITA currently. Working on updating this, because important to so many and will be included in LW DITA.
  • DITA is a standard, LW DITA WILL be.
  • Usually, TWs are NOT using engineer-created docs in reality. It’s an input, but the job of the TW is to translate, decide what to include, etc.
  • So how easy do we need to make it for engineers to contribute?
  • Better use case is for things like RESTful API documentation – pull in docs from github to your authoring tool.
  • Do Open Soure companies have a disadvantage?
    Since not willing to pay TWs, they are most interested in lowering the barriers for the community to produce + contribute content.
  • Traditional DITA: Task / Concept / Reference
  • DITA 1.3 has more topic types for increased specialization; e.g. Troubleshooting
  • (IxiaSoft) Internal/ External commenting on docs
  • Compare DITA vs. Flare – a matter of scale. DITA better for bigger scale
  • Do tools have good support for reviewers? Who needs to know the tool in order to comment, review, etc.
  • Almost 700 objects in DITA – only 40 in Lightweight DITA
  • Flavors of Markdown? Github is the winner. rST, proprietary

#6 Best practices for documentation navigation

Description:

  • What best practices exist for documentation navigation?
    • Should you implement progressive disclosure?
    • Shortened navigation titles?
    • 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 all together?

Scribe: Jessica Parsons

Top Takeaways:

  • Thinking about what no nav looks like is scary & interesting. This would be a good topic for next time!
  • Search prevalence changes how people approach content.
  • “It depends” – on product, on users, on goals.

Notes:

  • Shortened navigation text
    • Visual and auditory
    • Front-load important, distinguishing information
      • Between & within items
    • Action verbs at the start are helpful
    • Don’t have two options that sound the same or are hard to distinguish.
  • Searchable context
    • How to have essentials be read by people
      • Searching & jumping to one section, for example, safety warnings
    • Long pages are searchable, and people are used to scrolling.
  • “Time to Knowledge” – What is the quickest way to get the info I really need?
  • What if we don’t tie nav to titles? Stub sections?
  • Navigation can pose friction for readers, but also for writers.
  • Section numbering:
    • Good for technical reference material
    • Not as friendly for consumer products
    • Can be a nice waypoint, but it also assumes linearity
  • What about no navigation?
    • Chatbots: To replace or augment navigation?
    • Search: What used to be the index
    • Scannability is important
    • TOC is nice to get an overview
      • Expand all/collapse all is helpful
    • PDFs
      • Have TOC navigation, can search, kind of like a really long webpage in these ways
    • Every Page is Page One?
      • Lots of repeated content, because people don’t read front to back – they want all of the steps in one place.
      • Links save repetition, but they’re a bigger hassle to read.
  • How to make sure that people read safety warnings?
    • Have people click a button and read a pop up to get to the next step

Session 1 Notes – TC Camp 2018

#1 Chatbots

Discussion of chatbot topics from morning workshop:

  • Where do chatbots and techcomm intersect
  • Is your company considering implementing chatbots?
  • Have you seen or used chatbots “in the wild,” and were they effective?

Scribe: Tonie Flores

Top takeaways:

  • Chatbot gives automatic response to a message.
  • Examples of uses:
    • Gather information interactively rather than via Google email responses.
    • Gather diagnostics.
    • Auto responses to FAQs.
    • From linguistics: Syntax and semantics for training chatbots. * Agent = does the action and * patient = acted upon.
  • Tools: WIT. AI owned by Facebook. Used for testing to provide POC. Requires domain expertise.
  • Content already tagged and cleaned is half the battle.

Notes:

  • Chatbot = automatically responds to my message.
  • Lives on a platform; extension of your  product.
  • Start with live chat to get patterns to automate. That’s when you would use automation.
  • Example: I’m looking for a job in the city.
  • Natural language processing. WIT. AI owned by Facebook. Only (?) for testing to provide POC.
  • Train to detect intents, traits, and value of questions. Requires domain expertise. How many ways can someone ask a question?
  • Getting content, traits, and values is half the battle.
  • Syntax and semantics from linguistics used for training chatbots.
  • Agent = doer; Patient = acted upon.
  • Patrick Bozek – EasyDITA has an example of use of chatbots for documentation.
  • Example of use of chatbot: Conversational ay to gather information. Alternative to Google search results page.
  • Chatbot helps gather diagnostics.
  • (?) Chatfield: A toolkit, quick and cheap.
  • RASA: Open-source…”gotcha”: Facebook  owns your data.
  • Cannot understand sarcasm; for example, So happy I had to wait 10 hours to get this information.

#2 Implementing open source documentation

Description: 

  • Creating documentation for an open-source project differes from creating documentation for proprietary software in these ways:
    • Engaging your community of developers to contribute docs to the project
    • Building your documentation tools to enable collaboration from non-staff contributors
    • Enabling continuous updates through a transparent review process
  • Share your experiences in helping to create docs that are useful for the developer community

Scribe: Wendie Ruano

Notes:

  • “Help wanted on docs”
  • To find out how to contribute: search for tags “help,” “docs,” or similar terms
  • Go to github.com, login/create an account, search for ways to contribute.
  • Your contributions are reviewed, possibly revised, rejected
  • Look for tutorials on the github.com site or (google: github tutorials)
  • Github has user groups and companies have accounts
  • Doing a getting started doc is a major and usually appreciated contribution
  • A good tactic is to comment, say you’re interested, and offer to help with the doc
  • Best to wait for response before wasting time
  • Tools: use Markdown or HTML as a backup
  • Use Jekyl for introductory web site building

#3 Techniques to interview SMEs to get info for the doc

Description:

  • What techniques do you use to get information from SMEs?
  • Sometimes the SMEs are still formulating concepts and reference material in parallel with the writing. Sometimes the information is split across SMEs.
  • Do you have any standard questions or standard ways to organize the information?
  • How do you record this base info ad digest it later?
  • 2 pre-votes and 16 at TC Camp

Scribe: Kevin Hufnagle

Top Takeaways:

  • Do your homework ahead of time.
  • Come up with a game plan.
  • Keep overall project context in mind (beyond specific feature).
  • Understand teammates’ expectations of you, your role, and adjust/change as needed.
  • Repeat back answers to minimize misunderstandings.
  • Encourage SMEs to describe and deliver use cases, caveats, & gotchas.

Notes:

  • Gather specs beforehand?
    • Product managers and software engineers co-write 1-pager design docs.
    • Same physical area as engineers helps. Be available to discuss and overhear developers.
    • If can’t sit co-located, solid design beforehand helps. Also be responsive in IMs & email.
  • Walkthroughs & demos
    • Sometimes TWs encouraged/expected to ‘try it ourselves’.
    • Recording interviews & IMs with SMEs helps in giving yourself 2nd, 3rd chances to understand nuances.
    • Use cases and pitfalls.
  • Up to TW to understand how other pieces in the system work.
    • Consoles tend to be easier to digest and create.
  • Types of questions
    • What-if scenarios
    • How piece fits in with rest of product & work flow.
    • Repeat back your understanding of the answer—resolves misunderstandings
  • Conflicting info?
    • If 2 SMEs have some “report ancestor”(?), reach out to them to discuss strategy.
    • Often the product’s value add and place in work flow story more nuanced than tech itself.
  • Patterns of release
    • As tenure on team increases, can detect and take advantage of similar themes and decisions across multiple releases (“punted [?] features”).
  • Team dynamics – how to interact with SMEs as only TW?
    • Understand and develop teammates’ view of your role.
  • Caution w/ documenting unreleased features.
    • TW serves as glue, sharing info among different teams
  • Digest base info later.
    • Recognize when SME is going down the rabbit hole. Don’t dilute notes!
    • Have a set of questions, general ideas to discuss ahead of time and come up with rough plan of documenting feature – encourages research
    • Mismatches are particularly important.

#4 TechPubs metrics that are meaningful for business / Why do tech writers have such a low perceived value?

Description: Why do tech writers have such a low perceived value? Why are tech writers constantly at the bottom of the IT totem pole? How can they establish greater value to the organization, removing questions about headcount, job reqs to backfill or not, etc., when they arise? In this discussion group, we’ll explore ways to communicate, measure, and track the value added by tech writers in an organization.

Scribe: Gayle Naylor

Top Takeaways:

  • Tech writers need to prove their value by gathering metrics. Here are some of the metrics that were discussed:
    • Page count, number of words, number of docs
    • Customer satisfaction, did doc influence purchase?
    • Topic reuse

Notes:

Most people in the group are starting to gather metrics and some are planning to.

Here are the metrics that companies are using or plan to use:

  • Page count or number of documents.
  • Customer Survey. After downloading a document, the customer is asked these questions: Was it easy to find? Was it clear? Did it help solve their problem?
  • Editor counts mistakes in manuals.
  • Readability. Put manual through Flesch reading test. (higher is better) This is in Word if you enable the feature. Lower grade level = easier to read. One person started using this in September.
  • Editing time.
  • Cycle time-calculating document project from beginning to end. (Track time to develop, time for SME review, etc.) Hours and calendar of time spent.
  • Number of topics touched in CMS. Topics touched ranged from 10% of content changed to 80% of content changed.
  • Create a final map and this starts the clock. Calculate time to release.
    • Cannot account for gaps when SMEs are traveling and are inactive.
  • Track topic reuse. A pdf converted to html is 100% reuse.
  • CMS is not a project management system.
  • Track the number of times specific types of topics are used. (Single-product company.)
  • For RFPs, see how much of the document is new and how much of it is reused.
  • More interesting is reuse of document types-user manual and RFP for example.
  • One company uses a CMS to generate reports to calculate dependencies. It counts how often a topic is reused (“where-used” functionality).
  • Topic reuse vs. other reuse such as legal disclaimers. Consider making these separate topics.
  • How do you measure tech writer performance? How much does the document cost? Reuse is cheaper to produce.
  • Better documentation lowers technical support costs. Lots of companies don’t know what they spend now!
  • Ask customers how much of product cost would you assign to documentation. Did customer use the documentation to make their buying decision?
  • Google Analytics hooked to the doc site (longer sessions and more hits.) Can watch people walk through document site and click to sales site.
  • Editing, writing, formatting tools-bucket the time to measure
  • You get what you measure. What behavior do you want?
  • Here is one approach: total number of points per month based on effort.
    1. Knowledge transfer
    2. Size
    3. Complexity
    4. Media/images

#5 Building an online portfolio

Description:

Hiring managers and recruiters are an impatient lot. They want to assess your writing ability before the phone interview. An online portfolio can make your phone ring faster.

Let’s discuss:

  • What to include in your documentation portfolio
  • Where to host it (Dropbox, LinkedIn, a personal website, GitHub, etc.)
  • When to include proprietary/NDA’d content

Moderator: Andrew Davis

Scribe: Tatyana Perelmuter

Top Takeaways:

  • Portfolio is an expectation of recruiters. (add link in resume/LinkedIn)
  • Problems with using links to Word documents: IP, NDA, copyrights, deprecated documents. Ask permission, add disclaimer, search and replace product name.
  • Publish on LinkedIn, GitHub, Writer Residence
  • Static web site generator. Host with Square Space, AWS
  • Make a copy of publicly available documents to send if deprecated

Notes:

  • Online portfolios are expected
  • What to include and where to post it?
  • Explaining what you’ve done on employer web site is difficult
  • How to deal with links to publicly available documents that has been removed?
  • Legally you are not permitted to post copyrighted documents that you wrote for another company on your web site
  • Most people are flexible
  • You can explain why document written a certain way such as impossible deadline
  • GitHub can take all document formats
  • Keep you online presence concise
  • gohugo.io-static web site generator. Link to living documents you’ve written on other sites
  • Include disclaimer explaining the why and how, and the tools to create document (To protect your IP). Edit open source documents to showcase it
  • Cannot freely use documents that you wrote for a company that no longer exists.

#6 Your favorite authoring tools (and why)

Description:

  • FrameMaker, Arbortext, MadCap, Author-It, XMetaL, Oxygen, Word, RoboHelp, wikis, etc.
  • There are quite a few toolchains for people to make technical documentation. Which tools are the best for which situations? This would be a round table discussion with input from all attendees on the capability of familiar tools. The goal would e to map out which tools are frequently used together (identify toolchains) and which common toolchains tend to be used in which situations.

Scribe: Dan Littman

Top takeaways:

  • Tools need to talk to each other better.
  • People need to plan for the inevitable move to structure.

Notes:

  • Google Docs – cloud feature.
  • Adobe FrameMaker won’t be cloud-based any time soon.
  • Use X – what Y do you use with it?
  • From PDF to (?) not efficient.
  • Frame has no CMS, and can’t put it in Git or anything like that .
  • Structured refers to using a content model. i.e. the party to (?)
  • Author-It is structured but doesn’t use XML, so it is trapped  in that app — it is a binary, whereas XML ties (?) doc parts.
  • A contract with Boeing and a lavatory company to use a specific doc model to describe lavatories (?), so docs can merge into Boeing’s larger documentation set (or -?-).
  • Paligu (?) – she found it is the only tool that met all the requirements for the project.
  • People who converted PDF to Word and then edited it.
  • Frame – The master page wasn’t able to accommodate different content and formatting she wanted.
  • Frame doesn’t have the freedom of a DTP tool.
  • Frame – Tables are excellent; the best part.
  • User voice support tool – knowledge base.
  • Confluence – wiki tool, for knowledge base.
  • XMetaL – ideal client? He doesn’t really have one, but more people need to use structure.
  • In multiple docs, trying to figure out how to avoid duplication…is causing teams to become siloed because it’s too hard to show it all to potential.
  • Oxygen or XMetaL – Oxygen has lots of new features; but can be overwhelming (more for XML developers). XMetaL is easier to use.
  • XMetaL is a desktop tool, not cloud, but integrates with XML-based CMS – integrate to the repository of the content manager.
  • Now Frame can output good HTML – not like older versions that trashed it.
  • It’s really the habits of the writer – if people use styles consistently (in Word, for example), it’s easier to move to structure

Session Matrix – TC Camp 2018

This year we had 4 sessions each with 6 different discussions. Every discussion required a scribe and a facilitator. Scribes keep the notes and facilitators keep the conversation focused and make sure that everyone gets a chance to talk.  Both get special merit badges for their extra efforts!

Scribe notes are used during Camp Minimalist, at the end of the day, and saved here so you can access them later. These notes preserve not only what you learned, but give you access to what everyone else learned too!

Notes for each discussion have been posted to the individual session pages.

Workshops

  1. Pre-Camp API Workshop
  2. Adobe Workshop
  3. Chatbots
  4. Minimalism
  5. WordPress/SEO

Unconference Session #1 – Notes

  1. Chatbots
  2. Implementing open source documentation
  3. Techniques to interview SMEs to get info for the doc
  4. TechPubs metrics that are meaningful for business / Why do tech writers have such a low perceived value?
  5. Building an online portfolio
  6. Your favorite authoring tools (and why)

Unconference Session #2 – Notes

  1. API documentation practices
  2. Cyber security and the role of documentation
  3. Video/Audio – when are they better than print?
  4. Freelancing
  5. DITA, lightweight DITA, and markdown
  6. Best practices for documentation navigation

Unconference Session #3 – Notes

  1. Improving search in technical content / WordPress-SEO
  2. Complex doc systems with Markdown and Git / Markdown for techcomm
  3. Instructional design for tech writers / eLearning and the role of documentation
  4. Securing remote tech writing work
  5. Tools for documenting REST APIs / Breaking into API documentation
  6. Ways to simplify complexity

Unconference Session #4 – Notes

  1. Minimalism
  2. Documentation for the Internet of things (IoT)
  3. Getting user feedback
  4. Future of DITA / Content reuse mechanisms in DITA
  5. Career paths after tech writing
  6. Writers and product usability