DEV Community: DocumentWrite

Remix: 10 Minute Docs Audit

DocumentWrite — Thu, 02 Nov 2023 20:44:27 +0000

Remix is a JavaScript full-stack framework that allows developers to write frontend and back-end code. The framework was recently acquired by Shopify.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Not sure what inspires someone to get up one morning and say, "Yes, I'm going to build another JavaScript framework," but here we are. That being said, I liked Remix's doc's landing page. I was up and running in less than 3 minutes. I think Remix is trying to solve for performance, but I'm not sure. The landing page was full of buzzwords such as "focused on web standards" and "modern web app UX." I wish I could say I care about web standards, but honestly, I want to code up a website in an afternoon and keep it moving. Perhaps I'm not the target audience?

	Score
Purposeful	1.5
UX Experience	2
Accurate	3

Are you interested in a FREE Quickstart audit for your company? Start here.

OpenAI: 10 Minute Docs Audit

DocumentWrite — Tue, 24 Oct 2023 01:25:30 +0000

OpenAI is an artificial intelligence toolkit for software developers. Software engineers can use OpenAI to create chatbots, content generation, and so much more.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Quick confession. This is not my first time using OpenAI's API. Since 2022, I've built 3 OpenAI applications. But that being said, it's not like I use the framework every day.

OpenAI was delightful to use. The instructions are clear and accurate. And as a bonus, all of the prerequisite code is in the QuickStart. No need to go to the Python documentation to figure out how to get a virtual env up and running.

If you're interested in quickly getting started with AI development, OpenAI's docs deliver.

	Score
Purposeful	2.5
UX Experience	3
Accurate	2.5

Are you interested in a FREE Quickstart audit for your company? Start here.

Claude: 10 Minute Docs Audit

DocumentWrite — Mon, 23 Oct 2023 15:30:00 +0000

Claude is a large language model, LLM, created Anthropic. Claude can answer questions and produce content similar to ChatGPT. Just like ChatGPT, there is a UI for end users, and an API for developers.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Developers need an invite to access Claude's API, and the experience went downhill from there. The landing page and the Getting Started page were hard to navigate. I found myself clicking between Claude's landing page, Anthropic's API docs, and Anthropic's GitHub page. A nightmare. 😤

According to Anthropic, it was in the process of making multiple LLMs, but the only one I could find was Claude and Claude Instant. Where are these other LLMs?

That's it. Wasn't impressed with Claude's/Anthropic's docs. They weren't nearly as well organized or helpful as ChatGPT's.

	Score
Purposeful	1
UX Experience	1
Accurate	NA

Are you interested in a FREE Quickstart audit for your company? Start here.

Nextra: 10 Minute Docs Audit

DocumentWrite — Sun, 22 Oct 2023 02:32:48 +0000

Nextra is Next.js's site generator. It comes with mdx functionality out of the box, and has server capabilities(just like Next.js). Developers can use Nextra to create websites and documentation portals.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Not going to lie. Wanted to LOVE Nextra. The first two minutes started off as a lovefest for Nextra. The landing page discussed the benefits of Nextra for the developer and the content writer. Nice.

However, the trouble started when I tried to run Nextra locally on my computer. I downloaded all the dependencies and got this weird error Error: spawn ENOENT. Tried to remedy it but failed.

I had high hopes for Nextra, but not getting a sample app running on my computer was a big letdown and a poor and frustrating experience.

	Score
Purposeful	3
UX Experience	1.5
Accurate	1

Are you interested in a FREE Quickstart audit for your company? Start here.

Starlight: 10 Minute Docs Audit

DocumentWrite — Fri, 20 Oct 2023 02:44:23 +0000

Starlight is a documentation platform based on the Astro. It similar to Docusaurus, but you aren't forced to use React.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Starlight's user experience game is strong. The cli was colorful and delightful to use. I didn't have to install another framework, and when I was finished running the script, I had a Hello World project up and running.

That being said, I'm not sure what Starlight is adding in the documentation framework world that doesn't already exist. The landing page lists a ton of features, but it fails to explain why I should give it a try.

	Score
Purposeful	2
UX Experience	2.5
Accurate	2

Are you interested in a FREE Quickstart audit for your company? Start here.

Markdoc: 10 Minute Docs Audit

DocumentWrite — Thu, 19 Oct 2023 02:55:49 +0000

Markdoc is a content authoring tool, creating by Stripe. Markdoc is open-source and natively integrates with Next.js and React.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Not going to lie. I was expecting great things from Markdoc and came away from this review disappointed. The landing page implies that Markdoc is for everyone, but it doesn't take long for the docs to get into the weeds of JavaScript transpilers and setext headings. 🤯

I just wanted to get a CMS running by lunchtime so I can spend the rest of the week focusing on content. I don't have the brain power to ponder the the pros and cons of Markdoc's tag system vs MDX.

I'm sure Markdoc is a lovely tool, but it's strictly for the nerds. Looks like I won't be giving up Docusaurus anytime soon.

	Score
Purposeful	1
UX Experience	1.5
Accurate	2

Are you interested in a FREE Quickstart audit for your company? Start here.

Marko: 10 Minute Docs Audit

DocumentWrite — Tue, 17 Oct 2023 01:49:44 +0000

Marko is a library that extends HTML markup, and enables users to build dynamic UIs.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?

3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

I had difficulty figuring out what problem marko was trying to solve. The landing page listed a bunch of features. But honestly, I wasn't sure who it was for and why should I care. When I headed over to the Getting Started Guide, I was greeted with what seemed like a reference guide. There was a tutorial, but it lacked context and wasn't compelling.

I'm sure Marko is a great library, but I wished the documentation spelled out who Marko was for and what problem they're trying to solve.

	Score
Purposeful	1.5
UX Experience	1.5
Accurate	2.5

Are you interested in a FREE Quickstart audit for your company? Start here.

Streamlit: 10 Minute Docs Audit

DocumentWrite — Sun, 15 Oct 2023 03:32:56 +0000

Streamlit is a Python UI builder, very similar to Reflex. Streamlit enables data analysts, and data scientists to quickly turn their graphs, and models into a web app(without JavaScript).

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?
3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Streamlit offers an incredible user experience. On the landing page, you can start coding right away or head over to the Getting Started and learn more about the project. Streamlit has a lot of Pandas examples, which leads me to think that this application was built specifically for data scientists. Many data scientists work with Jupyter, which is great for analyzing data but is not really made to be an end-user app.

But I digress.

It took me less than 3 minutes to get the demo up and running. Once I was able to get it up and running in my browser, I was blown away by the UI. It was clean, and I could export code and even do a screencast- out of the box. The demo provided me with a ton of value and features.

The Getting Started guide and the demo exceeded my expectations. It was an absolute delight to walk through Streamlit's documentation!

	Score
Purposeful	2.5
UX Experience	3
Accurate	3

Are you interested in a FREE Quickstart audit for your company? Start here.

Reflex: 10 Minute Docs Audit

DocumentWrite — Sat, 14 Oct 2023 02:01:13 +0000

Reflex is a Python framework that allows developers to create 100% Python web apps (no JavaScript required).

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?

3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Tons of fumbling. Not sure who was the bigger problem, me or the docs. First, I was having trouble setting up venv. Then, it took me some time to install Reflex. All that effort and all I got was an error message when I ran the Reflex Init command. 😭

How can Reflex improve? Please list how to create and activate venv, don't make users have to fumble through the official Python docs. Also, if reflex init really is broken, please fix it ASAP.

Things that Reflex did well? Loved the docs intro. It was obvious that this application was for Python devs who don't want to deal with JavaScript!

	Score
Purposeful	3
UX Experience	2
Accurate	1

Are you interested in a FREE Quickstart audit for your company? Start here.

Million.js: 10 Minute Docs Audit

DocumentWrite — Thu, 12 Oct 2023 21:36:04 +0000

Millioin is a virtual DOM replacement for React. Practically this makes React apps more performant.

I run a technical documentation business specializing in writing and editing documentation. I made this series to share my insights and help projects craft impactful documentation.

What's The Criteria?

3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

Like many apps that promise performance gains, as a newbie, I didn't know if I had a data-heavy React app that needed optimizing. The QuickStar didn't come with an application ready to go, and I had to quickly spin up my own create react app, CRA. This felt like an interruption in my workflow.

Once I installed Million on my CRA, I realized the docs didn't make it obvious for me to test if Million indeed improved the performance of my app. So, I quickly created another CRA sans Million and checked the load speed of both applications. Million was faster and loaded in under 1 second. This was cool to see in action, and I wish this hands-on-test existed in the documentation.

All in all, the Getting Started section was ok- but I would have preferred to come out of that part of the docs with a working app, or an interactive way to test a site w/ Million.js installed.

	Score
Purposeful	2
UX Experience	1.5
Accurate	2

Are you interested in a FREE Quickstart audit for your company? Start here.

ToolJet: 10 Minute Docs Audits

DocumentWrite — Wed, 11 Oct 2023 20:09:33 +0000

ToolJet is an open-source low code framework to build and deploy custom internal tools.

What's The Criteria?

3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

ToolJet had a strong start. ToolJet made it clear what problem it was solving and who the intended audience was. In the first couple of paragraphs, ToolJet is a low-code tool, BUT I'm free to use any database I want. And Python and JavaScript. Sweet.

Then, the experience went downhill from there. There were multiple paths to get started, and they all seemed equally troublesome. If I wanted to get started locally, I had to use Docker. I know that Docker is an industry standard, but I still don't like it. It's bloated and one of the very few tools in my stack that I have to create an account for.

The second option I tried was to deploy ToolJet via DigitalOcean. I'm sure that I would have figured it out if I had 5 more minutes, but I didn't have 5 more minutes.

In conclusion, I'm not a fan of ToolJet's user experience. I wish they would swap Docker out w/ a tool like Gitpod. Also, I wish they had one happy path instead of presenting me with so many options so early in my ToolJet journey.

	Score
Purposeful	2.5
UX Experience	1.5
Accurate	2.5

Are you interested in a FREE Quickstart audit for your company? Start here.

Astro: 10 Minute Docs Audit

DocumentWrite — Tue, 10 Oct 2023 19:24:05 +0000

Astro is a front-end framework. It hasn't been around for a long time, but Astro has a very dedicated community. Astro also puts a special focus on developer documentation and education.

What's The Criteria?

3- Excellent
2 - OK
1 - Poor

Purposeful: Does the QuickStart explain what problem it's trying to solve? Who is the intended audience?

UX Experience: How seamless is the experience? Must the user create an account to get through the Quickstart? Does the Quickstart elicit a sense of joy and achievement?

Accurate: Are the instructions correct? Are they complete?

The Results

It took me a little over 6 minutes to create a working app, and I had some spare time to tinker with the code base. I was skeptical about launching the Hello World app in the browser, but it turned out to be a good and satisfying experience. That being said, it wasn't obvious how I could fork or download the code base.

Finally, what the heck is the .astro extension all about? What exactly is a component island? In layperson's terms, what does it mean to have zero JS runtime overhead? Astro threw a bunch of concepts at the reader without entirely unpacking them in a way that the user can get on board with Astro's feature set. Astro was snappy and fast, but was that because of the Zero JS, the component islands, or the astro extension?

	Score
Purposeful	2
UX Experience	2.5
Accurate	3

Are you interested in a FREE Quickstart audit for your company? Start here.