Documentation workflows based on Markdown and GIT
Scribe: Matt Ness
- 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
- 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.
- Writing for it, publishing it, managing localized content, process engineering, best practices
Scribe: Alan House
- 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
- How to prepare your context for localization?
- Some LSPs will localize screen shots
Metadata and Categorization strategies for technical writers
Scribe: Shari Clare
- 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
- 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
- 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
- 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 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
- 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
- Standards as they apply to the technical writing profession, process, and data items.
Scribe: Karl L. Leader: Bonnie
- 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)
- 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.
Scribe: Todd Lewandowski
- 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)
- 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)
- 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
- 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
- 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
- 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
- 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.
- 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
- What is the most efficient way to teach a traditional writer how to write topic-based content?
Scribe: Liane Takahashi
- Provide overview, introduce paradigm, high-level why’s
- Define topic types
- Provide samples, examples; demonstrate improved usability
- Define information types
- 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?
- Practical apps
- Use cases
- 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 – 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
- Style guides can encompass much:
- Entire doc structure
- Visual elements
- 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
- 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
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
- 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
- Creating social media forum posts
- Small articles / forum posts
- Align with marketing – align with needs for deliverables from other departments.
- Consistency – working – usability testing
- Inspiration and guidelines for injecting humor into tech docs
- Your favorite technical communicator joke
Scribe: Tom Magliery
- Humor is conditional in many ways
- Different things work in different media.
- Different things work for different audiences.
- (Ironically) Using humor is contrary to the idea of removing distraction.
- Salesforce won an award for humor in tech docs for Trailhead.
- The danger of humor is that it’s cultural.
- What’s funny in one context isn’t in another.
- Lawyers and politicians are fair game.
- What can be done in tech docs?
- Lighter tone as appropriate.
- Use puns and wordplay to catch the user’s eye.
- Writers can be more liberal in internal communications.
- Epigrams could be useful.
- Metrics showed humor made readers more receptive, and they read more.
- Use juxtaposition, surprise, hyperbole, irony, puns.
- More about SFDC (?) — funny things tend to be re-tweeted
- Content for mobile devices.
Scribe: Laurie d’Armien
- Consider user’s environment.
- Consider space for content: length and width per device.
- Use responsive app design and ensure content fits on all devices
- Reference Ann Rockley for mobile content
- Examples: DITA, epub, iPad
- Style guide is essential
- Reference Pronto forums for examples of responsive help
Taming the MS Word Monster When Moving to XML
- Top gotchas when moving from Word to XML.
Scribe: Ben Colborn
Essential is some kind of consistent taxonomy structure
- Tech pubs and education solutions/collaboration
- Difficulty in setting standards across organizations.
- Reduce overlap by converting legacy documents to structured
- Separate authoring from publishing
- Everyone says the want XML for reuse, but they really want control over Word.
- Can have any number of info types as long as authors understand them.
TC in an Agile Environment
- While an Agile environment spurs a wide variety of experiences, writers must ensure that docs are complete every sprint, and that reviews are built in to the plan.
Scribe: Elizabeth Semmelmeyer
- Wide variety of experiences.
- Need to include docs as part of the process.
- Agile often gets blamed, but it’s really implementation.
- Agile is designed for small teams.
- Significant lack of design docs.
- Big picture isn’t detailed; best to start with a small piece.
- Doc tasks must be visible, and included in sprints.
- Reviews should cross multiple scrum teams.
- Constant refactoring.
- The time to bring up issues is in the retrospectives. Track issues at each scrum team meeting.
- Writers are on multiple teams. Writers shouldn’t be on multiple scrum teams.
- Scrum master creates stories and facilitates meetings. Should assign owners to reviews.
- Dev has other priorities.
- Many meetings aren’t relevant to documentation.
- Content spread across scrums; multiple doc tasks.
- Complete doc tasks every sprint.
- Ensure team gets scrum training.
Promote Yourself via Social Media
- Using social media for self promotion and job searches.
Scribe: Talya Flowers
- Join different groups related to your field.
- Connect with like minded individuals in your field.
- Step outside your comfort zone
- If you have 500+ followers, you are an influencer.
- Participate by liking, following various blogs, sharing relevant articles, and making a presence in your communities to expand horizons and jobs will come to you!
- Facebook, Twitter, and LinkedIn used by majority in group
- Twitter is nebulous because of the 140 character restriction.
- Use relevant hashtags. Post articles of interest to show that you’re relevant and knowledgeable.
- Use HootSuite to post to multiple social media sites at once, tracks hits and likes even geographically.
- Use LinkedIn to promote your business. It’s visible to prospective employers.
- Business vs. Personal:
- Be cautious about the content you post
- Personal and business should not mix
- Twitter is the best option for self promotion; potential employers can see how active you are and how much you think about it.
- Use best judgement and be polite.
- Retweets, @ mentions, and hashtags affect number of hits
- Write reviews
- Best time to tweet is during commute hours
- Use polls
- Hoot Suite
- Periscope to do mobile broadcasts from cell phones
- Skype for podcasts; accepts multiple participants
Keeping up with Industry Trends
- How to keep your skills honed.
Scribe: Jessi Lawrence
- Have a desire and make the effort
- Network. Participate in communities, blogs, etc.
- Create a community.
- Reach out: at conferences engage with vendors, speakers, peers
- Research competitor’s docs
- “Current” is already behind. How do we anticipate?
- What do we do? Conferences, networking, etc.
- Keep abreast of new books and articles
- What are other people doing?
- What do other groups use for tools?
- Explore terminology on the web
- Use consultants. They need to keep on top of what’s happening in the field.
- Always look for things to learn
- Attend Write the Docs meetups
- Techwrl blogs
- LinkedIn groups
- Read the requirements for job postings.
- Ask others to explain new trends and teach others.
- Git is collaborative and has sandboxes to try new things (all in markdown)