Newsletter: Alphadoc, vocab lookup, field, Open Assistant, Markprompt, content ops

by Tom Johnson on Apr 20, 2023
categories: ai • news

• Alphadoc: a tool for generating OpenAPI documentation and tutorials
• Using AI tools to look up words and provide mini-poems to help remember their meaning
• Become a Technical Writer (Sponsor)
• A USC office removes ‘field’ from its curriculum, citing possible racist connotations
• Open Assistant: An open-source chat AI
• Leading Content Design, by Rachel McConnell — Book review by Josh Andersen
• Mintlify taps AI to automatically generate documentation from code (Techcrunch)
• Markprompt: Build a delightful GPT-4 prompt for your docs

Alphadoc: a tool for generating OpenAPI documentation and tutorials

Alphadoc is a new documentation tool designed to generate documentation from an OpenAPI specification. It creates reusable blocks from your OpenAPI spec, which can be used in various sections of your documentation. Treating the OpenAPI spec as the single source of truth, Alphadoc validates the spec to ensure it’s error-free. Then each time you upload a new version, Alphadoc automatically updates your documentation with the changes: “Whenever you upload a new spec file, we automatically update all connected API endpoints and parameters referenced across your docs and tutorials. This feature significantly streamlines your documentation process and ensures the docs stay in sync.”

Alphadoc can also automatically generate detailed tutorials based on your OpenAPI Spec. It can also convert between Postman Collections and the OpenAPI spec.

Alphadoc looks particularly useful if you’re writing API documentation that relies heavily on the OpenAPI spec. However, the tool will likely expand to handle other types of APIs in the future. Alphadoc is currently in private beta. Learn more >

Using AI tools to look up words and provide mini-poems to help remember their meaning

I’ve been using AI to look up vocabulary terms. Not just to provide definitions, but to provide sample sentences, etymology, and mini poems for a list of terms. It’s fun and a lot faster than looking up words one by one. The most fun part is the poem, which is often delightful. Read more >

Become a Technical Writer (Sponsor)

Lean lesson plans designed and built by an expert — no impractical theory, no academic fluff, no condescension to “newbs.” Only learn what you need to need to know, as quickly and easily as possible, to gain work as a technical writer. Created by a professional with end clients like Verizon Wireless, PwC, and Dow Jones.

Responsive and constructive feedback — actionable critiques from your instructor on exercises, documents, and your portfolio so you become better at technical writing with every piece you write. There’s never a “put down” for messing up. Indeed, messing up is essential to learning! Learn more >

A USC office removes ‘field’ from its curriculum, citing possible racist connotations

The USC’s School of Social Work decided to stop using the word “field.” A memo explains: “This change supports anti-racist social work practice by replacing language that could be considered anti-Black or anti-immigrant in favor of inclusive language. … Language can be powerful, and phrases such as ‘going into the field’ or ‘field work’ may have connotations for descendants of slavery and immigrant workers that are not benign.” A department named “Office of Field Education” (within the School) is now the “Office of Practicum Education.” (The change is just within the School of Social Work, not USC-wide.)

In technical writing spaces, the word “field” is most often used when instructing users to “Complete the [X] field” in a user interface. There are also many “field” definitions to document in an API. Learn more >

Open Assistant: An open-source chat AI

Open Assistant is a new open-source AI chat service that was recently launched. This chat’s open-source nature makes it different from others. As an open-source project, Open Assistant allows you to download its code and run it locally as well as actively contribute towards its improvement. The documentation says the project aims to “make a large language model that can run on a single high-end consumer GPU” (in other words, running it on your computer). Unless you’re contributing to the project’s development, you don’t need to download anything to run it.

Open Assistant’s larger project vision is to make the technology available to all: “Open Assistant is a project meant to give everyone access to a great chat based large language model…We are not going to stop at replicating ChatGPT. We want to build the assistant of the future, able to not only write email and cover letters, but do meaningful work, use APIs, dynamically research information, and much more, with the ability to be personalized and extended by anyone. And we want to do this in a way that is open and accessible, which means we must not only build a great assistant, but also make it small and efficient enough to run on consumer hardware.”

I played around with Open Assistant and find it a welcome complement to the growing array of AI tools. Its language capabilities aren’t as good as the others (for example, it does a poor job of fixing the grammar of content I give it), but I’m excited by the way these technologies have been open-sourced. The Open Assistant chat interface is online here. Learn more >

Leading Content Design, by Rachel McConnell — Book review by Josh Andersen

Leading Content Design, by Rachel McConnell, offers a guide to content ops, which deals with the strategic management of content creation, publishing, and distribution within an organization (think editorial calendars, content audits, messaging reviews, content repurposing, etc.). In a book review, Josh Andersen says, “Rachel McConnell recognizes the tendency for content design teams to be spread thin and pulled in too many directions, resulting in shallow work that doesn’t get to make use of the teams’ design skills. She is careful to point out that without a dedicated ops person, it’s easy for content ops work to fall by the wayside, even for content teams that appear to be organized into mature, established hierarchies. Her approach to doing this work effectively is to view ‘the content team as a product itself’ and to go about content ops as she ‘would approach any other design project’.”

I haven’t written much about content operations or content strategy, but this book looks like an excellent, modern guide to ramp up on these topics. I’ve never thought about treating the content team like a product itself. You can download a free chapter of the book. Learn more >

Mintlify taps AI to automatically generate documentation from code (Techcrunch)

Mintlify is a VS Code extension that automates documentation for the code you write. Developers need only highlight a chunk of code and click a button called Generate Documentation to auto-write the comments for that code. You can see an example here. Techcrunch says, “The company’s platform reads code and creates docs to explain it, leveraging technologies including natural language processing and web scraping.”

One of Mintlify’s competitors is Documatic, which “automatically generates change logs and explanations from code in addition to documentation.” However, Mintlify says it “provides ‘significantly’ higher quality results than its rivals, and — unlike some — doesn’t force developers to host documentation on a cloud service.” Although it doesn’t host the docs in the cloud, the Mintlify VS docs say “We never store your code, but your code does leave your machine.”

Given that not many tech writers like to dig into source file comments in engineering files in the first place, Mintlify might be a welcome addition. Read more >

Markprompt: Build a delightful GPT-4 prompt for your docs

Markprompt builds a GPT-4 prompt based on a specific set of docs. For example, after providing a GitHub repo URL or a folder of Markdown or HTML documents, Markprompt trains its AI on the content and then builds an interactive GPT-chat based on it. Unlike other AI chats, Markprompt sticks with the sources you trained it on. You can publish the prompt either as a React component or as a web component (the latter just involves using some JS, CSS, and HTML).

Markprompt also offers analytics about the queries. These natural language style queries could lead to better feedback about what information users want to know, leading to better insights about the documentation experience. Traditionally, queries that users type into search features in docs tend to be vague and unhelpful when analyzed. If AI chat interfaces become a primary interaction point for users with docs, and companies can analyze those interactions, the data could be enormously helpful in understanding user terminology, pain points, technical levels, and other details. In short, the chat analytics could create a large demand for better docs. Read more >