Sarah Maddox's Blog, page 6

More than writers, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Alan Porter presented a session titled Why Technical Communicators Should Be More Than Writers. The alternative title is Why Technical Writers Shouldn’t Be “Writers!”

Alan started his career as a technical author, writing technical manuals for the Concorde aeroplane (British Airways). He said there are mentions in history of Roman times of people consulting the manuals. Even hieroglyphs and cave art are technical writing. He showed us some examples of writing that are hard to read, and touched on best practices:

Structured content
Topic-based authoring
Simple language
Consistent terminology
And more

What is our role?

We may think we’re hired to be technical writers, but actually our job is to communicate complex material in a way that’s as simple as possible.

Alan said this is the main takeaway from this session:

Your customer does not care where your content comes from.

What the customer wants

People want answers to their questions: 70-80% of people come to a website because they have a question. The questions are primarily in 2 groups:

Discover, learn, and train
Get answers to product or service questions, fix a problem, and enhance their usage of the product.

Most documentation is feature-focused, whereas people want to know how to do something or what the benefit is to them.

Customer experience and brand experience

Documentation and the product should work together to make a good user experience. Alan showed us an example of a tech guide for a product where cables and ports were colour-coded to ensure easy installation. The manual showed diagrams that corresponded to the physical pieces.

The most important thing for companies to focus on is customer experience.

Technical writers are not just writers. We’re the key differentiators. We drive customer experience because we understand the customers and the market.

Every time a customer interacts with content, that’s a brand experience. Alan showed us a page of diagrams that was obviously an Ikea guide, but did not have the brand name anywhere. We all knew the brand anyway.

Next we looked at a Lego guide, which presented the same experience.

Alan said this is the way we should be thinking: Content should align with the brand and the product. Looking back to cave diagrams and glyphs, Alan said that humans have been communicating in a visual way for a very long time.

However, the diagram must convey the message you want. Alan showed us an engineering diagram that was intended to show the rings on Challenger would crack at a certain temperature. The diagram was dense and full of information, and did not convey the intended message.

Visual thinking

Before creating a diagram, we must understand the data. Then we need to decide how to convey it.

Another important step is abstraction. Alan showed a series of pictures of a face, moving from a photo thru various simplified drawings to an emoticon. Babies will react to a smiley face icon before they react to their mother’s face.

Symbols and icons help people understand something quickly. They become part of the culture. But before using them, make sure the meaning is clear.

There are standards for symbols and icons. For example, for car maintenance manuals, an automotive committee (I didn’t catch the name) has created a standard set of symbols for use across companies.
Be aware that certain symbols mean different things in different countries. An example is the thumbs up symbol, which has an unacceptable meaning in some places.

Think about colour. For example, in China white is the colour of funerals and morning. Other cultural aspects include whether people in a photo are wearing shoes or not, or the amount of white space on a page.

Alan mentioned many more cultural and design aspects that you need to be aware of. Visual communication is complex!

Where the content will be used

Consider where people will be viewing your content. For example, if they’ll be outside, it may be hard to read on a computer screen.

More to consider

Alan touched on animation, sound, and video. Video is an enormously popular way to consume content. As the next generation grows up, their primary interaction with content will be through voice.

We also had a quick look at augmented reality (AR) in technical instructions.

Alan’s recommentation

Examine a screenplay or a comic book script, and see how those were translated into visual content.

In conclusion

Thank you Alan for an engaging look at our changing role.

How analytics can change your world, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Analytics! They’re all the rage, and something I’m very interested in. David Payne presented a session called Analytics Can Change Your World. The subtitle of the talk was Or Justify Your Existence.

David’s goal in this presentation is to help us find the data that will help us prove our worth within an organisation. He said that the tool you use is not important. It’s what you do with it that matters.

The story of a team’s journey into analytics

David told the story of his team, which started from a small size with little clout. The team also had no insight into how their content was used or how often downloads occurred. They didn’t know who used the docs.

They started by collecting data using surveys. They had no way of finding out where users started from. The survey consisted of 20 questions. They had 300 responses over 3 years. The results were largely that the docs were “the worst ever seen”, “horrible”, and so on. There was no actionable feedback.

Next they added feedback links to the doc pages. Received thousands of responses. Not one of them was about the docs themselves.

The team also now knows how many people download the docs. The number has increased from 4 downloads in 2013 to more than 60,000 in 2017.

What to do if no-one is reading the online help?

At first, page views for the online help were very low.

Advertise – for example, add a banner on the printed docs.
Encourage add a hook in the product itself (Clippy?) to encourage people to view the online help.
Engage – talk to customers about how people use the online help.

David showed how the page views for the online help increased year by year.

Using your metrics

When you have the data, you need to start asking questions. David walked through these:

Which OS and browser are they using? David mentioned that his business stakeholders wanted this metric, even though to him it’s not relevant. Lesson: Have the pieces of data you want, but be ready to answer all sorts of questions.
Did the searches yield the results that the user wanted? For example, some information is legitimately not in your help because it’s relevant to other organisations, but people still search for it. In David’s example, over 60% of search results were not the ones the customer wanted. Tactic: David ran focus groups with customers. Many of the customers said that they turned off the online help for their users. The reason was that the product was very configurable, and thus the screenshots and information in the help were for the baseline system, which was not useful in a highly configured system.
How many page views per product? This result was not very useful, as it showed nearly 50% under the category “other” – these relate to search results and the home page, rather than single pages. This result did show, however, that there were 2000 topics in the docs. That’s too many for people to navigate around. David’s team is now working on reducing the number of topics and on improving context sensitivity.
How effective is context sensitivity? See how often people are arriving on the first page of the help as opposed to specific pages.

Next steps

Some strategies are to examine the data:

Focus on improving the high-traffic pages. Create a home page that highlights the most popular topics, so people can find them easily.
Find data for pages that have no views. Find out why people aren’t going there. If the page is important, raise its visibility. If the content is irrelevant, consider removing it entirely. David’s team managed to cut 400 out of 2300 topics.
Examine the search queries. For example, the number one search query was “transcript”. Discuss this with the product team and ask why people can’t find the transcript. Make the application so user friendly that the docs are not necessary.

Market the data throughout the company. Product managers may be able to glean the features that need more support. Development and QA can see which areas of the product the customers find tricky. Customer support may be able to use your data to support their own findings.

David discussed a few more questions we can ask about the data. He remarked that there’s no such thing as too much data.

In conclusion

Thanks David for a great overview of the type of analytics we can gather and how we can use the data.

Mentoring and being mentored, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

As a senior technical writer, mentoring and being mentored are much on my mind. Carrie Sheaffer and Eva Miranda presented a session titled, Be the Best You Can Be: Mentoring and Being Mentored.

As an introduction, Eva talked about her positive experiences with her mentor at uni, and how she strives for a growth mindset. Carrie talked about the moment when she realised that she was now a senior tech writer, and thus the one people looked to for advice. It was scary and wonderful and empowering.

Eva and Carrie met through STC, then started work at the same organisation, and kind of fell into an informal mentoring relationship. Instead of an informal mentorship, they recommend a more formal approach in which you define and measure your goals.

There are many types of mentorship, including:

Peer to peer
Speed
Traditional
Group
Network
And more

Perhaps you’re already mentoring someone…

… but don’t know it. If you’re helping a junior team member and advocating for them, then you’re already mentoring them.

You can be a mentor without being a manager. The mentor gives advice, whereas the manager gives rules.  Mentors are interested in your growth, while managers are responsible for your performance.

Defining your goals as mentee and mentor

A mentee (person being mentored) has certain goals, such as job satisfaction, opportunities to look out for, career advice and leadership opportunities.

The mentor also needs to know what they will get out of the relationship, even if it’s a little less tangible. Examples of their goals are to get a skilled team member and increase the performance of the team. Many mentors also gain satisfaction from giving back and sharing skills.

At the start of the mentoring relationship, the mentor and mentee should sit down and establish their goals. They should also review their goals and the achievement of the goals at regular intervals. The relationship should be reciprocal.

The mentoring relationship

Another good idea is to get to know each other. See if there are any shared interests, hobbies, or activities.

Be positive and open, and be sure to praise effort as well as skill. Make connections at the workplace, hold regular one on ones, and work together on the relationship.

Schedule fun outings, and aim for levity.

Feedback

Carrie promised that feedback doesn’t need to be scary (even though it actually is!).

Some tips:

Distinguish between something that is a personal style preference versus a rule. For example, the mentor may have a preference, or the rule may come from a style guide. The mentee can choose to follow the former, but has no choice about the latter.
Talk about a piece of writing, rather than just asking them to rewrite it. Sometimes the talking through the topic is so much better than what was written, and the mentor doesn’t need to do any more.
Make suggestions, like “what do you think about trying…”
If you see a repeated pattern, don’t comment on every single occurrence. Just mention it once or twice, and say there are more occurrences.

Remember that the goal is for the mentee to grow, not to show what’s wrong. The mentee is thankful when the mentor takes time to explain the reason for feedback on a doc, rather than just enter the correction.

A tip for the mentee: Don’t freak out!

Feedback should go in both directions. The mentee should review the mentor’s work as well as vice versa. The mentee has something to contribute, and the mentor makes mistakes. The mentee can ask something like, “I noticed you did this, can you explain why?”

The mentee can learn as much from giving feedback as well as from receiving it.

When there are disagreements

What do you do when you have disagreements about the way to do something, and you can’t resolve the disagreement?

Get other opinions. Remember there are different viable ways of doing things. Make the discussions constructive, and don’t become emotionally invested in a solution.

Remember: The goal is to improve.  When you have a product that is better, everyone wins.

The mentor must own their growth

The mentor can’t tell the mentee how to grow. The mentee defines their goals and the direction they want to go in. Then they identify the help they need, and discuss that with the mentor.

Ask for help when you get stuck. (Eva and Carrie showed us a haiku that they wrote to illustrate this section. It was fun.) Especially if there’s a deadline, ask for help directly.

If you’re working on something in a certain direction, and you think there’s a better way to do it, speak up.

The problems

There can be problems in a mentoring relationship. Mentoring is hard, and it’s no fun if the relationship is not working. Maybe you just don’t get along, or maybe the mentor is just not good at mentoring or good at their job. Perhaps the mentee is not progressing.

There are some options:

When you’re reviewing your goals, suggest a change or suggest ending the mentorship.
Suggest that the mentor moves to a different role.

When the mentee advances to a new level

On the positive side, any perceived problems in the mentoring relationship could be because the mentee has advanced so far that they no longer need the same level of mentorship. An approach is to address this when reviewing your shared goals. Perhaps the mentor needs to change their mentoring methods and the mentee needs to change their goals.

The mentor can start giving the mentee more advanced projects, and reducing the amount of detailed, low-level feedback.

In conclusion

Thank you Eva and Carrie for a lively and thoughtful look and the mentoring relationship.

Optimizing your content like an engineer, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Sara Feldman‘s session was titled, Optimize Your Content Like an Engineer. She talked about incorporating engineering principles and quantitative measures into continuous content optimization, and how this would bring better cross-departmental collaboration and return on investment (ROI).

An engineer’s approach is to change your strategy and direction, rather than just change your approach.

Inverting your perspective to outside-in

Just because we may be better at putting the customer first than other team members such as some engineers, that doesn’t mean we have no room for improvement.

Things are changing all the time, especially in terms of technology. Our method needs to evolve accordingly. We should challenge our assumptions and the ways we do things, to improve customer experience.

Trends

Sara mentioned trends such as artificial intelligence (AI), and self-service as a starting point for support calls.

Strategies to address the above trends:

Automate engagement with AI.
Distribute consistent knowledge across your support channels.

Sara said:

Content is like water

This comparison helps us separate the message we want to convey, from the format of that content.

Content engineering

Content strategy is what we should be doing, and content engineering figures out how we should do it. A content engineer bridges the gap between content strategy and development.

Content engineering makes it possible for writers to deliver good value.

Measures and methods

Sara touched on the following measurement techniques:

Leading and lagging indicators – Leading indicators are activity oriented. They represent the work you do, and are directly actionable. Lagging indicators are outcome-oriented, and they help you gain insight into the future. They’re harder to influence because you can’t change them directly (for example, you can’t directly change customer satisfaction (CSAT) measures). They confirm a pattern.
Vanity metrics – Page views, time on page, bounce rate, number of active/unique/new users. These things are easy to measure, but they don’t tell you much about outcomes. Vanity metrics have an important place, to take the pulse, look at trends, get started. To get benefit from them, you need to correlate them to outcomes that you’re looking for. Reference: Sara recommended an article called Measuring Page Velocity with Google Analytics .

Here are some methods drawn from engineering principles:

Eliminate unnecessary work – This technique is sometimes called maximising work NOT done.
Refactoring – This means cleaning up your code. The goal is to simplify the design of existing code without changing its behaviour. The principles apply to content too: fix unhealthy dependencies and other sources of confusion and clutter.
Data-driven design – Use data to determine what your customers need and want. The data should guide your decisions on a continuous basis. Use the data to define your minimum viable product (MVP). In other words, trim down your scope to get the content to your users sooner.
Retrospectives – Debriefings to determine what went well and what didn’t, and use the results to improve your content and processes.

Future of content

Sara said this topic is kind of fun and scary at the same time. She mentioned Information 4.0, and the Information 4.0 Consortium. A group of very smart people who’ve got together to decide how information needs to behave in order to support Industry 4.0 (the trend towards automation and data exchange in manufacturing technologies).

Some of the recommendations for Information 4.0 are that content should be:

Molecular – separate from format.
Spontaneous and triggered by contexts.
Ubiquitous – online, findable, and searchable. Gated content (content behind a signin) doesn’t qualify.
Personalised based on customer profiles.
Dynamic and continuously updated.
Accessible to other systems, e.g. via APIs. This is also known as content as a service.
Independent of channel, thus usable in multiple contexts.

So, content must be ready for anything? That’s hard to achieve. Here are some litmus tests from Sara:

Chatbots (conversational UIs)
Voice assistants (smart speakers)

To work with the above interfaces, content must be independent of format, and must come in small chunks.

A mature content experience

These are the requirements Sara mentioned for a mature content experience:

Prioritise user experience and intent over authors. Intent means modifying the type of results you’re giving based on what you think the user needs in their current context.
Blended content delivery. Our content is still too often presented based on our internal organisation structure. For example, help content, user manuals, training, all in separate places.
Every snippet is snippet one. (This concept is based on the well-known concept of every page is page one.) Snippets must be able to stand alone. We need to be conscious of the language we use and how we reference other things that may not be available.
Feedback loop to business objectives and products & services. Your customers are giving you lots of useful information as a result of your content analysis – make sure this feeds back to the business.

In conclusion

Thank you Sara for an interesting and engaging look at content optimisation.

The trending value of tech knowledge, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Tom Johnson presented a session titled Tech Comm Trends: Providing Value as a Generalist in a Sea of Specialists.

Tom kicked off his talk by remarking that posts on his blog about trends have way more clicks than other posts. So he decided to dig deep into this topic. Find the trends that we should dig into, what we should pay attention to.

Trends, innovation, and what to focus on

Companies come and go. Some of them are big for a while, then disappear. Could the same thing happen to our role as technical writers?

One of the reasons companies fail is because they stagnate. They don’t pay attention to innovation. Maybe we, as technical writers, should ensure we don’t coast and that we look towards innovative techniques.

OK, so how do we decide what we should focus on? Which areas of innovation are important? For example, perhaps we should look at the trend towards focusing on user experience (UX) design. Some say technical writing is dying out because all products now have great UX design, thus rendering docs unnecessary.

The growth of technical writing roles

Tom showed some stats from the US Bureau of Labor Statistics over a period of five years that show technical writing roles growing by 8.2%. In the same period, software development roles have grown by 15.7%.

Growth projects over ten years show the ratio of technical writers to software developers will stay more or less the same (1/33 in 2016 as opposed to 1/35 in 2026).

Yet technical writers feel that the number of engineers they support grows year on year. Also people have questioned the methodologies used to collect the data, and whether things like off-shoring have skewed the picture.

How our role is evolving

Tom quoted some content from Ellis Pratt’s Cherryleaf podcast. 92% of technical writers agree that our profession is changing. But where are we headed? Just a few of the recent trends include:

Wikis
Semantic web
DITA
Content strategy
Chatbots
Docs as code
AI
Augmented reality
And more

We need to make some kind of decision about what to focus on, so that we can prepare for the next few years of our role. How can we sort transient novelties from reliable trends? Do potential employees value a broad skill set and a flexible outlook

Some sources of information

Job ads. if no-one is looking for technical writers with a particular skill (such as chat bot content) then that skill is not in demand, at least for now.

Research. Some academics publish thorough research on trends in our industry.

Looking at the above sources, Tom pulled out some conclusions:

Some job ads focus on professional competencies like written communication, project planning and management, etc.
Another focus is on subject matter knowledge. Many of the job ads emphasize experience in the subject area rather than tech-writer-specific skills. For example, candidates should know a particular programming language such as C or Java. You may even need to show examples that prove your knowledge. So, being willing to learn is not good enough.

Technical versus writing skills

People with technical knowledge, such as proficiency in a programming language, are often favored over those with writing skills. Tom posited that this could be because technical skills are easier to measure than writing skills.

There’s now a distinction between developers who write docs and technical writers. Another term is technical technical writers. There’s a feeling that, when publishing developer-focused docs, it’s more engaging for the audience to have developers writing the docs.

Is this the future we’re heading towards – the distinction between technical technical writers and technical writers? And why might this be so?

Tom discussed the fact that technology stacks have exploded. In 2005, there were a relatively few large vendors offering single systems. Now we have an explosion of development tools, vendor systems, and APIs. This complexity makes employers value technical knowledge more highly.

Learning technology

Given the increasing technical complexity, we need to figure out how to learn a new technology.

The Pomodoro technique involves using a focus app to learn for a specific period of time such as 20 minutes, then take a break and start again.

Learning creates a plastic mind. Tom said perhaps it doesn’t matter that much what you’re learning, provided you’ve created a learning mindset in yourself.

Do companies know what they need?

There may be a disconnect between what companies say they want and what they actually need. Compare the quote about Henry Ford and customers who want a faster horse!

Tom argued that companies need a technical writer who can analyse the customer experience and the audience and create the docs that address those, rather than focusing on the technology aspects of the product. This focus on customer experience is what excites the business executives in the company!

In conclusion

Thank you Tom for a well-thought-out presentation on the complexity of our roles and environments.

Sketching is like technical communication, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

The title of this session drew my attention: How Sketching Is Like Technical Communication, presented by Elizabeth Alley.

Elizabeth noted that this session was for visual learners and non-visual learners. I guess that covers me then.

Improving docs and measuring quality, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Early on Monday morning, Barbara Giammona presented a session called Measuring and Improving the Quality and Completeness of Your Documentation.

The idea for Barbara’s session came from a request from her boss to figure out ways to measure the effectiveness of documentation. She shared some of the resulting initiatives. She emphasized that measuring docs is tricky, and the initiatives are a work in progress.

Barbara covered the following topics:

Content
Processes
Productivity
Working with partners

Content improvement: Partnering with customer support

Barbara’s team talked to the global customer support team about improving the content of the manuals, partnering with them in a more deliberate way than before.

Some of the feedback was fairly obvious, in retrospect. Things like removing the number of notes and appendices by moving the content into the main doc, breaking up long sentences, and shortening titles. The customer support team also suggested sending high-impact docs for shared review.

One surprising request was to increase the number of acronyms, as they make the content more concise.

The measurement is that the number of customer-reported issues related to the docs goes down within 1, 2, and 3 years.

Content improvement: Hearing from customers

Barbara has made a deliberate effort to get in touch with customers directly. When customers come on site, for example to do beta tests of the product, Barbara makes an effort to meet them. She sets up review sessions, walks around at customer conferences asking people for feedback on the docs.

The measurement is improved customer satisfaction, year on year. To get these results, the teams uses a customer satisfaction survey.

Content improvement: Refactoring of much-used and visible docs

In the documentation plan, the team includes the time and effort needed for improvements to the docs. Tasks include:

Improving and adding/removing graphics
Breaking up long chapters
Simplifying language
Moving installation instructions into one place
Review FAQs for potential inclusion into the docs

Another important goal is to take customer feedback into account when designing new docs.

The measurement is fewer complaints from the support and delivery team.

Process improvement: Length of review cycles

Barbara talked about performing a root cause analysis for the problematically short reviews. Review cycles were too short, and doc tasks were being compressed into shorted periods.

The root cause analysis looks very thorough. People wrote Post-it notes about potential causes, which the team then grouped and analysed. The team used the “five whys” technique to ask up to five questions about why a problem arose. This technique helps find the root cause. Barbara walked us through the process in detail with examples.

The measurement is improved experience of reviews in new projects. Barbara joked that the reviews should no longer make you feel suicidal.

Process improvement: Productivity

The topic here is resource availability and the ability to estimate workload. It’s difficult to estimate the effort required for each project. The technique is to gather data from completed projects (hours spent) and use those for future estimates.

The measurement is accurate cost estimates and not having to scramble to find resources.

Process improvement: Partnerships/outsourcing

Barbara talked about working with a team outside the company to complete documentation tasks. At first the relationship failed due to lack of skill in the partner team.

The technique to solve this problem was to visit the partner team in person and provide training sessions. Training includes things like effective writing and how to with subject matter experts.

The measurement is to see whether the partner team sets targets and delivers on par with the other teams, and whether the US leads are writing less and leading more.

In conclusion

Thanks to Barbara for an enjoyable and thorough talk about techniques for improving our documentation.

Season of Docs is now ready for tech writer exploration

Technical writers around the world can now explore the open source organizations taking part in Google’s Season of Docs program. It’s time to start preparing your project proposal!

[image error]Season of Docs provides a framework for open source projects and technical writers to work together on the projects’ documentation. It’s a program run by Google in collaboration with participating open source organizations.

The program kicked off in March 2019 by inviting open source organizations to apply to take part.

The list of participating open source organizations is now available on the website.

The next step is for technical writers to apply to take part in the program.

Explore the tech writing project ideas and contact the organizations

It’s exciting to see the variety of open source organizations taking part, and the technical writing project ideas that each organization has on on offer!

If you’re interested in working on open source docs as part of the Season of Docs program, now’s the time to start planning your project proposal. You can contact the organization(s) that you’re interested in right away, and discuss your proposal with them. Talking up front is a great way to ensure you submit the best project proposal that you can. Then you’ll be ready when the technical writer application phase opens on May 29.

Some hints from me

Each open source organization has published a list of ideas for technical writing projects they’d like to complete within the Season of Docs program. (Follow the links from the page of participating open source organizations to see each organization’s project ideas.)

Remember that you’re the one with technical writing expertise. Write your proposal based on your experience of other projects. Include your plan for design and execution of the project, and scope the project so that it’s achievable within the Season of Docs time frame.
You can split an organization’s idea into smaller chunks and write a proposal for one or more of those chunks.
You can also propose an entirely new project idea of your own, based on your exploration of the organization’s open source product and existing docs.
Read the Season of Docs FAQ and technical writer guide for information on how much time you can expect to spend on a project, and about long-running versus standard-length projects.
Do get in touch with one or more organizations to talk about the projects they have on offer. They’ll be able to help you design a proposal that you can then submit to Season of Docs. It’s the organizations who’ll eventually choose the technical writers to work on their docs during the program.
You can talk to as many organizations as you like, and you can submit more than one application to Season of Docs, though only one application will be accepted.
Your project proposal forms part of your application to Season of Docs. Read the technical writer guide and application hints for help with creating your application.
Make your project proposal count. There may quite possibly be other technical writers proposing to the same organization.

Questions and discussions

Here are a few places where you can learn more and ask questions:

Join us on the Season of Docs Slack workspace or discussion mailing list, anytime. For information on how to join, check out the page about discussion channels on the Season of Docs website.
Will you be at STC Summit in Denver on May 6-8 (next week)? I’ll be speaking on Tuesday, May 7, at 2pm about open source, documentation, and Season of Docs. See the session description in the summit app (you need to be logged in). You can also grab me for a chat in the conference hallways.
Join the Write the Docs online meetup in mid May. Write the Docs Australia and Write the Docs India are hosting a joint online meetup (webinar) on May 15 (APAC time zone). Join us for an overview of Season of Docs! The webinar is free of charge and is open to anyone interested.

Hope to see you in one of those places.

Interoperability and the FAIR principles – a discussion

This week I’m attending a conference titled Collaborations Workshop 2019, run by the Software Sustainability Institute of the UK. The conference focuses on interoperability, documentation, training and sustainability. I’m blogging my notes from the talks I attend. All credit goes to the presenter, and all mistakes are my own.

Patricia Herterich from the University of Birmingham presented a session on “Interoperable as in FAIR – A librarian’s personal point of view“.

A simple definition of interoperability: the ability of computer systems or software to exchange and make use of information. People also talk about semantic interoperability and other interpretations of the term.

Data interoperability

Patricia introduced the FAIR principles: a set of guidelines that aim to ensure data is:

findable,
accessible,
interoperable, and
reusable,

by both people and machines. FAIR principles focus more on the semantic aspects of interoperability rather than the technical aspects.

Patricia highlighted a big problem: Interoperability is not a well defined term. No-one knows what it means.

Some organisations have developed tools to assess data interoperability:

The Dutch Data Archiving and Networked Services (DANS) organisation has developed a FAIR data assessment tool (see the prototype) that attempts to measure data interoperability.
The Australian Research Data Common (ARDC) has also developed a FAIR Data self-assessment tool.

Software interoperability

For software, we can think of defining interoperability in this way:

Use of open standards
Use of platform/plugin architectures
Use of common libraries and package managers

Patricia pointed out that FAIRsharing.org offers various standards, but there are already well over 1000 standards there.

So how does a researcher go about choosing the right standard? How do we train researchers to make data FAIR? Patricia left this as an open question for discussion.

Questions and comments from the floor:

The FAIR principles were originally developed for data. Does it make sense to apply them to software?
The FAIR principles seem like just a catchy way of packaging techniques that have been applied for a long time.
Interoperability is not simple, and we need a set of user-friendly tools.

Thank you Patricia for a good discussion of the complex world of interoperability.

A portal for life science training resources

This week I’m attending a conference titled Collaborations Workshop 2019, run by the Software Sustainability Institute of the UK. The conference focuses on interoperability, documentation, training and sustainability. I’m blogging my notes from the talks I attend. All credit goes to the presenter, and all mistakes are my own.

Niall Beard from the University of Manchester presented a session on “TeSS: The ELIXIR Training Portal“.

TeSS is a life science research training portal that provides access to the training tools and platforms from various universities and other institutions around the world. TeSS provides metadata and a classification scheme for the items in the registry. The items are divided into two overarching categories: events and materials.

[image error]

Getting data into TeSS

TeSS provides an online form for adding new training materials. TeSS also pulls in the material automatically, using things like:

Schema.org / Bioschemas
Website scraping, but that’s not an efficient  or reliable way of gathering data
XML schemas, but it’s tricky to get developers to use the XML schema to create content describing their site
And more

Schema.org provides a lightweight way of structuring online data. This is the most useful type of integration for TeSS, and is used by other content providers too. Schema.org has plenty of plugins that developers can use to apply the data to their applications.

Bioschemas.org is a community project that creates specifications for life science resources, and proposes those specifications for inclusion into Schema.org. The community is also working on tools to make bioschemas easier to create, and to extract and use the data.

Getting data out of TeSS

TeSS provides widgets that you can use to display TeSS content on a website, and a JSON API for interacting with TeSS programmatically.

Thanks Niall for a good overview of the TeSS training portal.