Leon Barnard from Balsamiq wrote up a great series of challenges and solutions for the docslikecode.com website. His lessons learned are super helpful for all of us:
- Challenge #1: Documenting multiple product versions
- Challenge #2: Adding play/pause to animated GIFs
- Challenge #3: Giving the list pages a makeover
He summarizes the series best in his own words:
Static sites may seem to have more limitations than traditional CMSs or powerful technical writing tools. But if you can find a way around the limitations, you can reap the benefits that made static sites attractive in the first place. Markdown is easy. GitHub offers collaborative coding. A scripted robot can run a build command from a terminal. It’s writing excellent documentation that is tough. Fortunately, that’s what technical writers are good at. Having a developer liaison for the docs team can free writers from having to think about the limitations of the technology they’re using so they can focus on writing the docs.
What to do about the chatbot crisis It’s never been clear that messaging apps had a future as platforms. It is also a stretch to think of voice as a platform, at least in any general purpose sense. In either case it seems like a misuse of ‘platform’. Messaging and chat systems will continue to […]
This post originally published on https://gilbane.com
Orbis Technologies, Inc. and RSI Content Solutions Merge to Form a Global Content Management Software and Solutions Company
In this case study on docslikecode.com, Jennifer Rondeau shares her story of gaining the trust of her developer coworkers so that she could edit code comments for a remote management web service at Symantec. This is an excellent, in-depth piece, and I really appreciate her writing it up to share.
While Jennifer was writing up the story on GitHub and I was reviewing the case study, I asked her to clarify a couple of points she made about fully integrating with the development team. One was “Doc management was continually concerned that putting a writer into the code — writing code comments and code samples — would set developer expectations of the writers too high.” Ouch. She goes on to say that their root concern was about the extensibility of the model – they didn’t think it could scale across teams. While reviewing, she clarified to say that management didn’t want devs to think they could offload work that they ultimately were responsible for themselves, maintaining good code comments. Also, management found that the tech writers had much more code-savvy than originally thought, and the empathy and advocacy that writers could provide was well worth the risk in the embedded model.
Another point to clarify while drafting the case study was about doc build automation. In the end, they decided not to automate the doc builds as part of the code builds. I wanted to know: Was it a dev resources problem where doc builds were not prioritized high enough as compared to work on the services? Or, management didn’t want to invest the time? Or the writer didn’t find a way to do it herself? Or maybe the automation time savings wasn’t quite big enough for attention? She said, “Ultimately, the decision not to automate the Javadoc made sense — there are always pain points on either side of a decision like this.”
You can hear more from Jennifer in “Docs as Code: The Missing Manual,” co-presented with Margaret Eker at Write the Docs Europe 2016.
Next-generation customer experience How do you link customer experience operationally and improve CX beyond individual touchpoints to succeed throughout the customer journey? Read More Three millennial tech myths busted Ben Bajarin shares findings from a recent study of mostly 18-24 year olds. Many of you are likely to be surprised by at least one of the “busted […]
This post originally published on https://gilbane.com
After seeing my infographic above, one of my colleagues asked me why I am so passionate about JATS (Journal Article Tag Suite NISO Z39.96) and its sister tag suite, BITS. There are two big reasons: first, their suitability for the task, and second, the dedicated team of experts that designed them and continue to develop them. That doesn’t mean I’m not an advocate for other tag suites. I am, so long as they serve my passion about XML and using the right vocabulary for the job at hand.
Check out this great case study by Rachel Whitton, Technical Content Editor at Pantheon. Their product is a website management platform for WordPress and Drupal and the case study is available on docslikecode.com.
I love how eager and willing Rachel is to share her story with other practitioners who are wrangling content with these tools and techniques. She was Pull Request number 1 in the new GitHub repo where I’m gathering stories about treating docs like code. Super grateful for her story.
She presented “Delivering High-Velocity Docs that Keep Pace with Rapid Release Cycles” at Write the Docs Europe in October 2016. Well worth watching when you’re looking for both innovation and inspiration.
CX and the age of the appacus This Economist article about fintech in China is important not just for economists or financial technologists, but for customer experience professionals. China is “far and away the biggest market for digital payments, accounting for nearly half of the global total”. Beyond digital payments, there is Chinese fintech support […]
This post originally published on https://gilbane.com
Audubon, Pa.— March 14, 2017— RSI Content Solutions, creators of the RSuite Enterprise Information Management Solution, today announced the release of two new fully-integrated modules, RSuite Edit and RSuite Publish. Together, these applications enable RSuite customers to further enhance their ability to manage and produce print and digital content in a single enterprise-strength solution.
RSuite Edit provides a simple, user-friendly interface that allows RSuite users to seamlessly create and modify content directly within the publishing solution. Authors, contributors, editors, and reviewers can produce structured content in an intuitive, browser-based environment.
RSuite Publish provides an automated, template-driven capability to produce print and digital outputs, rather than having to rely on manual design processes. Publishers can automate the creation of both print-ready PDF and EPUB output with a simple click of a button.
“RSuite enables many organizations to cut the time between authoring and delivery in half,” stated Lisa Bos, CTO/EVP Publishing Solutions at RSI Content Solutions. “With RSuite, they deliver more and more consistent content through streamlined processes and automation. RSuite Edit and RSuite Publish make it even easier to include more users throughout the enterprise in publishing workflows, without needing special technical expertise."
RSuite is the MarkLogic-based enterprise information management solution optimized for the creation, management, reuse and delivery of multi-format, multi-channel content. It combines the power of the MarkLogic platform with an enterprise?strength workflow engine, a fully-integrated authoring and editorial interface, and an automated composition engine to support both print and digital outputs. For more information, please visit http://www.rsicms.com/rsuite-enterprise-publishing-solution.
About RSI Content Solutions
For over 16 years, RSI Content Solutions has been at the forefront of implementing content agility solutions for publishers, media companies, Fortune 1000 businesses, government organizations, and more. With headquarters outside Philadelphia, PA, USA, an engineering center of excellence in Chennai, India, and affiliate offices around the world, RSI has helped over 250 global organizations implement appropriate content agility solutions. For more information, please visit www.rsicms.com.
Rob Smilowitz and I are once again gearing up for the annual London Book Fair next week, one of the best events of the year. We’re in Stand 3B72 and will be giving demos of RSuite, complete with two brand new components we will be announcing the first day of the show!
A passion for learning is the most important qualification for an effective technical writer. You can become an ace technical writer by fine-tuning the way you learn. How you go about learning will make the difference between good results and great results.
Focus on increasing your mastery in:
- Learning technology
- Working with others
Regardless of the country in which you are working, you can use these Seven Habits of Highly Effective Technical Writers as a guide to mastering technical writing excellence.
1. Don’t Take It Personally (learn)
Great technical writers thrive on criticism. They understand that it enables them to improve and to improve the accuracy and readability of their content. So, don’t take criticism personally. Use it to your advantage.
2. Learn Before Asking (respect, impress)
Learn as much as you can from available resources before asking questions. In this way, you can respect others’ time and impress your colleagues with your ability to ask intelligent questions.
3. Ask (often)
Technical writing requires good people skills. Don’t attempt it alone. Ask questions. Ask for help.
4. Rewrite (always)
Pick 3 of your favorite writers. If you were able to see their first drafts, you’d probably think, “I can do much better.” The best writers in the world are the best re-writers. Always rewrite, rewrite, and rewrite some more.
5. Acquire Feedback (test, reviews)
Technical writing is almost never 100% in the first draft. Without adequate testing and review, accuracy is often unattainable. Make sure you get the feedback you need to excel.
6. Understand (before publishing)
When you start, you may not fully understand your subject matter. That’s fine. By the time you publish, make sure you do understand. If you don’t understand what you write, your readers are not likely to understand it, either.
If you write something, you need to understand what you wrote. Even if it is just a draft to show your editor, you need to either a) fully understand what you wrote, or b) have a list of questions. Do not write a sentence that you do not understand.
Notice things. Does the prototype work as expected? Are the user interface labels capitalized consistently? Ask questions. Make suggestions. Be a part of the product team.
Source (republished with permission)
Barry Saiff is a leading expert in technical writing outsourcing and managing technical writers. For more than 32 years, Barry has experienced technical writing outsourcing from both sides—as a technical communications leader in the USA, and as a manager of offshore technical writers and customer liaison in the Philippines. Barry frequently leads webinars and speaks at conferences. His popular 7 Habits series of blogs, infographics, and webinars has been featured by the Society for Technical Communication. He has consulted for a variety of companies to help them improve their content and content development processes. Barry is featured in the Content Wrangler webinar Managing Technical Writing Outsourcing in an Agile Environment. Find out more here. Learn more about Barry’s company, check out Saiff Solutions.
The post Seven Habits of Highly Effective Technical Writers appeared first on The Content Wrangler.
Information Development World 2017
Early bird pricing is in effect until March 31, 2017. Save $300USD when you register before then.
IDW is an annual, intimate, three-day, laser-focused content conference designed to prepare you for the coming artificial intelligence revolution. We bring together — in the heart of Silicon Valley venture-capital land—an impressive roster of knowledgable content professionals—innovators, artists, scientists, engineers, academics, and business leaders—in one big room and take you step-by-step through the topics that matter.
Your guided journey begins with a focus on the business activities, processes, competencies, and tools required to take full advantage of opportunities digital technologies provide us today and in the future. Each day has a particular focus and is divided into four bite-sized chunks, making it easy for you to have a-ha moments and identify next steps you’ll need to improve to prepare your content for the future.
May 15, 2017—Digital Transformation
Presentations will cover:
- Changing the way we work
- Leveraging design thinking for content
- Mapping content to the customer journey
- Creating engaging and memorable content
May 16, 2017—Thinking Strategically
Presentations will cover:
- Developing a content strategy
- Creating value for company and customers
- Connecting content to those who need it
- Implementing and maintaining governance
May 17, 2017—Innovation and Disruption
Presentations will cover:
- Overcoming the status quo
- Leveraging machine learning
- Understanding artificial intelligence
- Making content cognitive
Who should attend?
IDW is designed to serve the needs the people who plan, create, design, manage, translate, prepare, and deliver content to the prospects, customers, systems, devices and other machines that need it.
The conference will be particularly valuable for those whose job it is to create exceptional customer experiences with content.
I hope you’ll take a peek at our amazing roster of presenters and plan to attend Information Development World this May. It’s going to be an amazing event.
Questions? Just ask.
The post Digital Transformation: Information Development World appeared first on The Content Wrangler.
IBM Watson IoT and the digital twin. Industry 4.0. James Governor pulls together some thoughts and interesting examples of the digital twin model. His post was inspired by an IBM event with large industry customers, but as he suggests, the model has broader relevance. I would say the proliferation of IoT and integration with back-end […]
This post originally published on https://gilbane.com
Much appreciation to the people and teams who made this possible.
- Diane Fleming and Kelly Holcomb wrote and edited with me and worked tirelessly to craft this collection of inspiration, use cases, and ideas into a real true book.
- Andreas Jaeger wrote articles with me about CI/CD and documentation reviews, plus his sharp eyes reviewed early drafts.
- Richard Hamilton, XML Press founder, tested the GitHub instructions and uncovered issues in early drafts.
- Eric Holscher, cofounder of Write the Docs and Read the Docs, read the early draft and wrote great input and an awesome foreword.
- The OpenStack docs team and multiple dev teams have been an inspiration and constant source of education through the years.
- The Rackspace docs team went through this transformation and brought the development teams with them to share the vision of great docs.
- The Cisco Metacloud docs team, completely eager and ready to use GitHub for a brand-new docs site.
I am grateful for all the assistance and humbled by the opportunities I’ve had. Share your stories of treating docs like code by writing a use case yourself!
If you want to be inspired, read compelling examples, and learn more about the tools and ecosystem for treating docs like code, get your copy today.Buy Docs Like Code on Lulu.com
Creating documentation within an Agile team is both challenging and rewarding. Agile moves fast and emphasizes team collaboration. Many Agile evangelists think that being Agile means no documentation. The same amount of documentation is required in Agile. The difference is when and how that documentation is created.
Consider the following tips.
1. Join Daily Stand-Ups
A stand-up is a short meeting where the team reports on what they’ve done, what they plan to do, and anything preventing them from doing their work. If you’re not attending, you’ll quickly fall out of sync.
When attending stand-ups:
- Focus on team activities and priorities.
- Even if there are no changes to user documentation, listen and learn.
If you are not considered part of the team or are not invited to the stand-ups:
- The project may be extremely difficult.
- Inform the Scrum Master and Product Owner.
- Explain your role, and how your absence negatively affects documentation.
2. Write Documentation User Stories
User stories are the format used for defining software requirements in Agile. Stories take the form of:
“As a (role) I want to (do something) so I can (get something).”
- Should not cover every detail.
- Should not include implementation details.
- Should be used to start team conversations, where details are discussed and explored.
Documentation user stories highlight your work and how that work fits into the rest of the project. Software delivery is incomplete without documentation. Good Agile teams will appreciate your contribution.
Developers often loathe working on documentation. By politely insisting that documentation user stories are an integral part of the definition of done, you’ll gain respect and cooperation.
To write documentation user stories, define your audience, and consider WHY they need to read the documentation.
Is the audience:
- End users who are confused?
- Developers who need to integrate and extend functionality?
- Administrators who need reference information?
What is the desired result of reading the documentation? What problem does the documentation solve?
“As an end user, I want to read user help to understand a procedure.”
“As a developer, I want to read API documentation to avoid wasting time when integrating the system.”
“As a buyer, I want to see the documentation to make sure the system is complete.”
“As a technical support person, I want documentation to troubleshoot customer issues.”
3. Get Synchronized
Many Agile teams delay documentation until after delivery. This is a mistake. Any user interaction flaws the technical writer detects are delayed, and may never get addressed. You end up scrambling to document what you cannot understand because you weren’t in stand-ups.
If you are not a full team member, working on the same features at the same time as the rest of the team, you’ll always be behind.
You’ll be the first “smoke tester” for new features. You can make sure that user stories are consistent and don’t stray into “how to” territory.
A good team appreciates your non-technical perspective. Your team will want to know as early as possible if something is confusing or inconsistent.
Related reading: Mastering Technical Communication Leadership
4. Work On Documentation Debt
A technical writer’s work is never done. No product is ever 100% documented. Similarly, the development team always has a certain amount of technical debt tasks in their backlog.
Keep track of your documentation debt. When the development team is resolving technical tasks in the backlog, you can fill documentation gaps, write documentation user stories, or write that missing help for advanced features.
5. Use Intelligent Guessing
Because Agile moves so quickly, you may not have time to wait for the team to finish the UI before writing.
What can you do?
User stories are a great help to writers. With a good grasp of the UI, you can guess how the new features will work in advance. Just make up the steps and descriptions and be reasonable.
Then share your work with the team. Tell your team in the daily stand up that:
- You’ve guessed how the new features will work.
- They can use this to guide their decisions, or
- They can tell you what you’ve got wrong so that you can fix it.
At first, this can be daunting. “How can I know beforehand?”
Take advantage of inflated engineer egos. They love to point out errors. Encourage them to correct your guesses. Everyone saves time. They can focus on clarifying what is wrong.
It takes a big dose of both confidence and humility, but you’ll quickly earn the team’s respect. Yes, you’ll get things wrong. But you were going to make mistakes anyway. At first, the team will just focus on your errors. Eventually, they’ll use your guesses to guide them in developing features.
Agile is here to stay. The Agile Manifesto puts working products before extensive up-front documentation, but it never says that Agile is documentation-free.
In fact, the same amount of documentation must be done. If there’s no technical writer, the engineers must write it themselves (which they usually hate), or it doesn’t get done until a customer complains. At that point, it becomes a real challenge to figure out after the fact why the feature ended up as it was delivered.
Joining an Agile team as a technical writer isn’t an option. It’s a necessity. Using these five tips should help.
Fred Williams is a featured speaker in The Content Wrangler webinar, Managing Technical Writing Outsourcing in an Agile Environment. Find out more here. Fred is available to train your team. You can learn more about him and watch some free videos here.
The post Five Tips to Succeeding as an Agile Technical Writer appeared first on The Content Wrangler.
I’ve been reading up on artificial intelligence lately. AI, as it’s referred to, is a big topic with lots of exciting possibilities. Like many technology-inspired changes, the adoption of AI brings with it incredible promises for improvement. But, it also conjures up fear of impending disaster.
“No, robots will not organize a digital insurrection and take over the planet—at least, not anytime soon,” says Michael Rosinski, CEO of Astoria Software. “But, AI will usher in dramatic and significant changes to the way we live, work, and play.”
Rosinski’s right. Big change is coming. AI is already part of our daily lives. Fast food joints, banks and credit card companies and customer service departments of all types are using the power of machine learning to automate numerous tasks historically performed by humans.
Artificial Intelligence Will Eliminate Jobs, Not Work
Some researchers believe an interconnected, cognitive world of artificial intelligence will lead to the displacement of millions of workers. Others say it will lead to new artisan-type jobs that require a unique mix of technical know-how, interpersonal interaction, flexibility, adaptability, and problem-solving.
Just before President Barack Obama left office in January 2017, The White House published a report, “Preparing for the Future of Artificial Intelligence,” that details where job losses are expected to occur. Made for the White House by the National Science and Technology Council’s Subcommittee on Machine Learning and Artificial Intelligence, the report (removed from The White House website after Donald Trump took office) predicts:
- 83% of US jobs paying less than $20 per hour will be subject to automation or replacement
- Up to 47% of all US jobs are in danger of being made irrelevant due to technological advancements, with most job losses due to occur amongst the undereducated
- As many as 3.1 million car, bus, and truck driving jobs will be eliminated in the US due to the adoption of autonomous vehicles
Artificial Intelligence Isn’t Just A Blue Collar Threat
Disruption isn’t limited to service work and other blue-collar labor. White collar knowledge work will change, too. McKinsey & Company estimates that “as much as 45 percent of the activities individuals currently perform in the workplace can be automated using already demonstrated technologies.” Automating those tasks will save US industry an estimated $2 trillion USD in annual wages.
That’s not good news for some white-collar workers, whose jobs will be impacted by AI. Whether those occupations will be redefined—or eliminated—remains to be seen. What is certain is that some activities performed by knowledge workers in the digital labor pool will be automated, requiring a realignment of job roles and responsibilities.
Pretty much any job you can think of is riddled with activities that could be made more efficient if automated. Even mundane legal work—like appealing parking tickets—can be successfully automated.
How To Avoid Being Automated
In his farewell speech, outgoing President Barack Obama warned US citizens that “the next wave of economic dislocation won’t come from overseas. It will come from the relentless pace of automation that makes many good, middle-class jobs obsolete.”
Labor researchers say widespread adoption of AI can help US companies overcome less-than-impressive productivity gains. The benefits of AI—increased output, faster time-to-value, higher quality, improved consistency, and reliability—far outweigh the financial costs. A 2013 article in MIT Technology Review claims warehouses equipped with robots process four times the amount of orders as those that have yet to adopt automation.
Automation of routine, repetitive tasks, analysts say, allows workers to spend more time focused on creative tasks that provide value to the company and its customers. And, it allows companies to invest in highly-skilled, knowledgeable and experienced workers who will use artificial intelligence to augment their work.
Human-computer collaborations, some argue, will create an entirely new class of work. A quick search of the online jobs database Indeed provides a peek at the AI-related roles that companies are looking to fill today.
Thomas Hayes Davenport and Julia Kirby wrote a book loaded with advice for workers who want to ensure they won’t be replaced by technology entitled, Only Humans Need Apply. The authors say they believe viewing AI as competition—taking jobs away from humans—is a mistake.
”Instead of viewing these machines as competitive interlopers,” the authors say, “we see them as partners and collaborators in creative problem solving” that help us work better, faster, and smarter.
“In an environment where new skills emerge as fast as others become extinct,” Prising said, “employability is less about what you already know and more about your capacity to learn.”
Be Part of the Solution, Not Part of the Problem
Learning everything you can about AI—and how it can help you work more efficiently and effectively—is a good first step toward avoiding displacement. Develop an area of expertise, but don’t limit yourself.
- Seek out learning opportunities online (there are a wide variety of free, web-based classes covering artificial intelligence-related topics, and lessons shared by professionals, like this on machine learning from the folks at R2D3.
- Stay abreast of best practices being developed now by Partnership on AI and pay attention to what’s happening at the Association for the Advancement of Artificial Intelligence.
- Keep tabs on the great work from San Francisco-based, OpenAI, a non-profit research firm dedicated to helping us build safe AI systems that are available to everyone.
- Attend a conference—like Information Development World—to determine the best route forward, learn best practices, and to gain insight from others who have made the mistakes you’ll want to avoid.
The Future of Work Looks Bright
There’s good reason to be concerned about the future of work—and your place in the labor pool. But, let’s not assume the worst. Many tasks currently performed by humans will be automated. But that’s no reason to believe that the future of work is dim.
“Historically productivity growth has been associated with rising living standards for the bulk of the working population. There is no technological reason that this will not be the case in the future,” says Dean Baker, Center for Economic and Policy Research. There is no obvious basis for thinking that future technologies will be more harmful to ordinary workers than the technological developments of the prior seventy years.”
The future of work looks bright. Make sure you’re ready.
The post Artificial Intelligence: How To Avoid Being Automated appeared first on The Content Wrangler.
Next-generation 3D Graphics on the Web Thanks to Benedict Evans for noticing this. From his newsletter: Apple proposed web standards that give web pages access to the smartphone (or PC) GPU to run ‘general purpose computation’ (i.e. machine learning) as well as graphics. Very surprising – I’d have expected this from Google or Facebook rather than […]
This post originally published on https://gilbane.com