Recap 8/3 Sui AMA: Technical Writing with Randall & Clay

Jen:
Hello, everyone. Welcome to the next edition of our Sui AMA series, we're discussing the ins and outs of technical writing with our lovely guests Clay and Randall. Please introduce yourselves.

Randall:
Hi, my name is Randall, I've been in tech doc for longer than I'm willing to admit because it will let you know how old I am. I went to school for sociology, marketing, research, and statistics, but I couldn’t get a job in that field, so I taught myself how to use computers. Eventually, I moved to Seattle, started working as a contractor at Microsoft then transitioned to a tester. What caused me to stick with tech writing is that I found that I really enjoyed helping people get unstuck and solve their problems. My mission is to make great docs so that people consuming them can have a better quality of life, make their boss happy, and just be more successful professionally.

Clay:
I started as a journalist. I got into that business as an idealist but I found it to be actually incredibly depressing. Shortly thereafter, I got into public relations and then I got my hands dirty with HTML, which was really fun. I fell into tech writing and really enjoyed taking complex components and breaking them down, and then explaining how to use them seamlessly. It's really challenging and also incredibly rewarding. I ended up scaling my desire to tell people’s stories by helping build tools so they may tell their own tales.

.   .   .

Question #1: How can community members be involved with the Mysten project?

Clay:
I love this! Randall and I strongly encourage everyone to review the docs and help us make edits. It’s very simple, you can do this right now and we can show you how to conduct the edits in the GitHub web editor. On that note, we can also point out some cool features that might make the site look more attractive to edit and to contribute. You should know that at the top left of docs.sui.io, we now have the ability to display both the Devnet and the Latest Build versions. We also list all contributors at the bottom of each page, internal and external. And we offer a Source code link at the bottom to go right to the underlying Markdown file.

We work directly in GitHub right along with engineering so your contributions go directly into the Sui GitHub project.

.   .   .

Question #2: Why does the engineering team prefer Markdown over tools like Notion or Google Docs?

Clay:
That's a fantastic question. So in an ideal state, we would all have access to editors that would produce whatever format we desire. Engineers often are working at the command line already, and have access to a command line editor, whether that's something like Vi, or VS Code, which Randall and I are now using. They're more graphically based, and it's going to be a lot easier to edit large amounts of Markdown, which is essentially a plain text interface that gets transformed into HTML.

Randall:
Yeah, I agree with all of that. Primarily, we prefer it in Markdoc because we author in Markdoc. If you do a Readme in a GitHub repo, it's in Markdoc (I say Markdoc because I came from Stripe where we have a proprietary Markdown implementation called Markdoc). But I want to make sure people don't feel compelled or obligated to commit feedback in Markdoc. One of the goals that I have as a tech writer at Mysten, is I want to make our documentation accessible to people who want to be high-powered developers. I've seen this to be problematic in many of the places I've worked previously and I want to make a change.

So if there's something you don't get in the docs or it doesn't make sense to you, I would love to hear about it. It probably doesn't make sense to someone else and maybe we could reword it, or add some additional context.

Jen:
I think that's a lovely note because in my case, I'm only coming from a non-technical background. Maybe I'm misunderstanding how the author has intended to have people interpret this. Having technical writers in the team is such a gift because you're able to organize a lot of information in a way that is a lot more approachable.

.   .   .

Question #3: How much of your job is writing versus editing?

Randall:
So people always have this misconception about what we do as tech writers. I spend about 20% of my time actually creating content, 10% editing, and 60% of my time getting the information to turn into content.

Clay:
We spend a decent bit of time organizing materials that are submitted by engineering, and another bit of time goes to editing, just because we've gotten successful at encouraging so many requests for review of changes (pull requests) internally and externally.

.   .   .

Question #4: How do you two scale to meet the needs of dozens of engineers and thousands of users?

Randall:
Sometimes it's creative problem-solving, sometimes it's shifting priorities around.
Sometimes we meet and do interviews but a lot of it is just understanding what is going to be the most impactful and what's going to help users the most. Sometimes we do good enough documentation and then do a fast follow to improve or iterate on it. The more information and assistance we can give to people, the easier it is for us to then turn it into public-facing content.

Clay:
Exactly. Randall and I do work on the internal docs, just like we do with the external docs. A lot of tech writing groups will cordon things off and choose either internal or external docs. But we are dedicated to doing both and that's how we scale. We make it as easy as possible for people to do the right things for themselves, their careers, their users most importantly, and the product itself. We do this by supplying processes, templates, and guidance, as well as direct help writing the materials ourselves. Whatever is needed.

.   .   .

Question #5: What are the criteria for what a good doc looks like?

Randall:
This is like the magic question we, as tech writers, always ask ourselves. When I first started as a tech writer, I thought I needed to get 80% positive ratings on all of my content, but that is not really achievable because you have to consider all of the different types of people consuming the content.

The fundamental piece of what quality means to me is, can someone who's using this product, take this documentation and accomplish the task that they're trying to accomplish? If yes, then I think that meets the quality bar, but then there's lots of polish like:

• Is the topic easy to discover?
• Could I find the information I need when I need it?
• Why do I want to do this thing?
• Now you're done with this task, what should I do next?

So basically adding that level of navigation efficiency. You can do good docs with only some of those things but great docs need to have all of those, and then a lot of other polish as well.

Clay:
Great answer. So concretely, good documentation to me has some whitespace in it. I'm a big fan of Darwin Information Typing Architecture: https://en.wikipedia.org/wiki/Darwin_Information_Typing_Architecture

It states technical information can be broken down into three types:

1. Concept: If you’re just starting out, you're going to spend your time learning about Sui through the overviews and introductions in the Learn section of docs.sui.io.
2. Task: These are procedures, how-tos, and playbooks. Find them in our Build section. This is where you're going to be installing packages, creating smart contracts, and then building, testing, and publishing them.
3. Reference: These are tables, databases, and lists of objects where you can choose your own adventure. Find them in our Explore and Contribute sections.

Structure is key to keeping your users from muddling through conceptual material when they simply want to find the relevant command or sample. We organize this information based upon critical user journeys or CUJs where we predict what our audience needs to do. We focus on the user and not the tool.

And then we monitor the results: Analytics, Discord, and internal input. Soon enough, we can see what we have is working. And then we look for the next problem to solve, the gap that won’t appear in web stats.

Jen:
Well, you also pointed out something that I think some of the audience would want a bit more clarity on which is, what do you mean when you say a critical user journey?

Clay:
It's basically a user journey map to an overarching task. It helps you fulfill a goal without spending an entire day sifting through tools-based documentation to get your user journey completed. The doc should be used based on what you need to get done and then help you. You might touch a handful of tools to accomplish a single goal. That journey should be seamless and not take you down into the details of each tool unless absolutely necessary.

.   .   .

Question #6: What do technical writers do besides writing docs?

Randall:
As I said, I came from a networking admin background so I was able to do more in the networking space than just do docs. I did a lot of testing of security as well. I also did the UI design, which I just loved because then I got to put all the text on the screen and all the links to the docs just how I wanted them. The output we generate is the content that you see on the site but our primary role is to act as a user advocate in design discussions or in engineering meetings.

.   .   .

Question #7: How do you identify your audience?

Clay:
As an example, we really focused on app game developers, to begin with at docs.sui.io with secondarily the executive level folks and tech leads who make decisions. So you'll see the former served in the Build tab and the latter served in the Learn tab. Still, we present the Learn docs first because everyone should know the concepts.

At the same time we now have full node runners, and soon validators. We understand that our audiences will always be growing, and we have to work with all of our peers to serve them good information. These sessions are fantastic for making the call for identifying gaps and working with our peers to help us define each audience and really try to get everyone in the company and ecosystem involved in this.

.   .   .

Question #8: What is the best way we can help as a community? And will they be recognized?

Clay:
Yeah, that's a great question. We are considering creating a page in our Contribute section where you all can highlight your Sui-related work. I know a lot of you are content creators, for instance, and we would love to build a home for you to be able to highlight your creativity. Obviously, I'd need to work with folks internally to attempt to do that.

We want to recognize you all and that's why we definitely instantiated this automated GitHub profile to list down contributors at the bottom of every page. This is where we need your help primarily as tech writers, helping with the existing text and forming new sections. Obviously, that's our bailiwick, that's what we need to do.

But secondarily, we want to also highlight all the cool stuff you are doing. I'm seeing a lot of stuff in the Discord #content channel. Maybe, we give you all a pipeline where we have a page for community contributions, where you can literally just go in, and put a table together that’s linked to your text with a single sentence description of your creation, so people can leave from our site and we can get you more eyeballs.

.   .   .

Question #9: What's the most rewarding aspect of technical writing?

Randall:
I was a network admin and worked at a managed care company. I had a doctor that was the guy who approved or denied claims. Everyone has, perhaps, less than positive opinions of him in some cases. He was the kind of guy who was like ‘‘Hey, this is cool, go do this’’. Of course, you want to keep your job, so you go and try and get it done. I would spend hours and hours and hours learning how to do what he wanted me to do then oftentimes he wouldn't even use it.

The biggest obstacle I had in accomplishing tasks was learning how to use the new technology, learning how it works, knowing what else I need to do, and all the prereqs and stuff. Now everything I do as a tech writer is to help people do their jobs better, and that's what keeps me coming to work every day. If I do my job well, I can impact the lives of billions of people.

Jen:
Awesome. I cannot emphasize enough how helpful and empathetic both Clay and Randall are in regards to wanting to provide the easiest way to understand some of the things that we are pushing out in the world of Mysten and in Sui.