#1 MarkDown for Tech Comm
Scribe: Lynn Cooley
- 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
- 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.
- 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
- 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
- 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
- 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
- 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
- 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)
- 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
- 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
- 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
- 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
- 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
- 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