• Skip to primary navigation
  • Skip to main content
  • Skip to primary sidebar

Dion Almaer

Software, Development, Products

  • @dalmaer
  • LinkedIn
  • Medium
  • RSS
  • Show Search
Hide Search

Developer Platform

Developer Docs + GenAI = ❤️

January 17, 2023

We can do so much to help tech writers scale their efforts and help developers learn!

I know, I know, the current hammer du jour is “GPT for X“.  It behooves us to explore how a promising new technology can help us, and I believe there are two large reasons we should do so:

  • We (industry wide!) need all the help we can get to scale quality developer docs, so using these tools to help anyone writing the docs be productive is hugely valuable.
  • Developers are already looking at products like ChatGPT3 and asking questions of them. Currently the quality is variable depending on what is being used and the corpus that’s been available in the time window. We need to make sure that usage results in useful high quality output.

Helping produce quality developer docs

Every developer product or platform runs into the struggle of keeping high quality documentation up to date and comprehensive. It’s hard enough to execute on reference docs, let alone conceptual docs, tutorials, etc.

There is a resourcing issue at the heart of this:

  • It is very hard to hire great technical writers, because they need qualities such as:
    • Highly technical like an engineer
    • Able to explain and teach concepts
    • Write well.
  • Most (but not all!) engineers aren’t comfortable with taking on the writing aspects of their APIs
    • To scale, engineers, product managers, and developer advocates are needed to take on certain aspects of their docs (just can’t hire enough tech writers!)

GenAI isn’t a silver bullet, and no one would suggest we let the machines generate our documentation, but rather it can be a tool for the humans that do the writing!

  • As you write the docs, you can get various examples from a GPT-like engine that you then refine. ChatGPT3 is able to do a solid job at some of these tasks already, and is only going to get a lot better.
  • To take it to the next level, you can use techniques to refine such as few shot learning, fine tuning, or chaining so the engine can bias towards your view on best practice for whatever you are documenting. E.g. we can train on existing docs, sample code, etc.
    • Imagine including the ecosystem here too. Any great examples of content can be included in the training corpus. Just as some open source projects include the test suites from popular ecosystem libraries to make sure they aren’t broken in CI, you can do the same for content.
  • It will be great to be able to bring in not just knowledge, but also style and tone. It’s fantastic to unblock writer’s block by throwing raw content down and having the tools work for you. There are already tools that let you do things like:
    • Summarize this for me
    • Give me a good heading / title
    • Make this more concise
    • Flush this out with code examples
  • Boilerplate and grunt work… be gone.

These tools can give confidence to those who aren’t professional writers, which is huge!

Beyond docs, towards assistive learning

Helping create fantastic docs is itself a huge win for developers getting the most from your platform in a productive way. I just saw Codesphere sharing some results after they took the time to tune their docs.

But this work goes even beyond improved docs for devs.

You are now able to use the LLMs that have been tuned to your platform in other ways:

  • A chat interface for your platform knowledge
  • Get questions that target the knowledge that developers can use to train themselves
  • Integrate with popular IDEs so the information is there right where they are coding
  • …

Every day we see new examples of this, such as docs search like this:

There are a lot of challenges to go along with the opportunity, but it isn’t hard to imagine a world where you are pair-programming with Shopi and working with the GraphQL APIs is so much easier because of it, or Hydrogen components are being written for you that you can take and tweak, or converting from tech A to B is made trivial, and sooooo much more.

The tech is only getting better, let’s get on board now!


What do the bots think of this idea?!?

It felt appropriate to ask our robot friends for some of their thoughts on the topic, and here are a couple things that emerged:

Challenges of Automation in Technical Writing

As with any automated process, there are certain challenges that come with using GenAI in technical writing. One of the primary challenges is the potential for errors due to the automated nature of the process. While GenAI can help streamline the writing process, it cannot always guarantee accuracy. Additionally, GenAI may not always be able to capture the nuances and complexities of human language, which can lead to misinterpretations and errors.

Another challenge is the potential for bias in the automated process. GenAI relies on the data that is used to train it, and if the data is biased, then the output of the process can be biased as well. This can lead to incorrect or misleading information being generated.

Finally, there is the challenge of cost. GenAI can be expensive to implement and maintain, and it may not always be feasible for organizations to invest in the technology. Additionally, there may be a need for additional personnel to manage the process and ensure accuracy.

Benefits of Using Machine Learning in Technical Writing

Despite the potential challenges, there are several benefits to using GenAI in technical writing. One of the primary benefits is the potential to increase productivity. By automating certain aspects of the writing process, GenAI can help streamline the workflow and reduce the amount of time spent on manual tasks. This can help to free up time for more creative and complex tasks.

Additionally, GenAI can help to improve the accuracy of the writing process. By leveraging the data used to train the system, GenAI can help to ensure that the output is consistent and accurate. This can help to reduce the amount of time spent on manual proofreading and editing.

Finally, GenAI can help to reduce costs. By automating certain aspects of the writing process, organizations can potentially save money on personnel costs. Additionally, GenAI can help to reduce the amount of time spent on manual tasks, which can lead to cost savings in the long run.

Integrating GenAI into Existing Technical Writing Processes

Integrating GenAI into existing technical writing processes can be a great way to increase efficiency and accuracy. By leveraging the power of machine learning, organizations can potentially reduce the time spent on manual tasks and improve the accuracy of their documentation.

However, there are certain challenges that must be addressed when integrating GenAI into existing technical writing processes. One of the primary challenges is ensuring that the data used to train the system is accurate and unbiased. Additionally, organizations must ensure that the system is properly managed and monitored to ensure accuracy and prevent errors.

Finally, organizations must also consider the cost of implementing and maintaining a GenAI system. While the potential benefits are great, the cost of implementing and maintaining the system must be weighed against the potential savings.

Overall, integrating GenAI into existing technical writing processes can be a great way to increase efficiency and accuracy. However, organizations must ensure that they address the challenges associated with the process and consider the cost of implementation and maintenance.

Measuring Success when Using GenAI in Technical Writing

When integrating GenAI into existing technical writing processes, it is important to establish metrics for measuring success. This will help organizations to determine if the process is working and if any changes need to be made.

One of the primary metrics for measuring success is accuracy. Organizations should track the accuracy of the output generated by the GenAI system and compare it to the accuracy of the output generated by manual processes. This will help to determine if the GenAI system is providing more accurate results than manual processes.

Another metric for measuring success is efficiency. Organizations should track the amount of time saved by using the GenAI system and compare it to the amount of time spent on manual processes. This will help to determine if the GenAI system is providing more efficient results than manual processes.

Finally, organizations should also track the cost of implementing and maintaining the GenAI system. This will help to determine if the cost of the system is worth the potential savings.

Overall, measuring success when using GenAI in technical writing is essential for determining if the process is working and if any changes need to be made. By tracking accuracy, efficiency, and cost, organizations can determine if the GenAI system is providing more accurate and efficient results than manual processes.

Developing Best Practices for Using GenAI in Technical Writing

As with any new technology, it is important to develop best practices for using GenAI in technical writing. This will help to ensure that the process is efficient and accurate, and that the output is of the highest quality.

One of the primary best practices is to use data that is accurate and unbiased. This will help to ensure that the output generated by the GenAI system is accurate and unbiased. Additionally, organizations should ensure that the data used to train the system is regularly updated to reflect any changes in the industry.

Another best practice is to ensure that the system is properly managed and monitored. This will help to ensure that the system is functioning properly and that any errors are quickly identified and corrected. Additionally, organizations should ensure that personnel are properly trained in using the system and that any changes to the system are properly documented.

Finally, organizations should also consider the cost of implementing and maintaining the GenAI system. This will help to ensure that the cost of the system is worth the potential savings.

Overall, developing best practices for using GenAI in technical writing is essential for ensuring that the process is efficient and accurate, and that the output is of the highest quality. By following these best practices, organizations can ensure that they are getting the most out of their GenAI system.

And engineer and a robot working together to create better docs.

/fin

The rise of the extensible app platforms

May 24, 2022

I was excited to see Kenneth and his team ship the public beta of the Stripe App platform:

Today we are launching the public beta of Stripe Apps, a new way for developers to extend @stripe and build on top of our platform.

Some background on why we built Stripe Apps, what our platform enables you to build, and where we are headed.

🧵 pic.twitter.com/OC5HAnCzl3

— 🛠 Kenneth Auchenberg (@auchenberg) May 24, 2022

I was excited to dive into it, as I know that the developer experience would be high quality, and I wasn’t proven wrong. Great CLI experience. Great docs. What you have come accustomed too. As I read through the anatomy of what you are able to do with apps, I could see a lot of similarities with Shopify’s app platform.

The body of a Shopify store

Let’s dive into some anatomy. When chatting with one of my favorite new PMs, Ben Sehl, he shared an analogy of how a store is like a body… a metaphor which I will now abuse to kingdom come:

When you create a Shopify store, you get a simple, yet fully functioning experience… like a human with simple attire, let’s call them Shopi. How do you want to take this base and make it your own?

The first step that products and platforms give you is the ability to tweak the look and feel. This is where you start with theming. You can dress up Shopi in many ways, and make them unique. You can make the clothing yourself, or you can find manufacturers (theme developers!) that have pre-built quality goods that you can then customize from there. As the platform matures, so does the supporting ecosystem.

Now, there is a lot that you can do with the look and feel, but you quickly find that you need richer customizations. This is when the app platform comes in (often called plugins/extensions). The platform controls what can be extended. Can you replace limbs? The heart? The brain? How do you do this in a way that doesn’t destroy the body? A great platform allows for layers of extensibility, which is as much art as science. This is the type of work I love doing, and I am excited to see Shopify continue to refine these layers.

Shopify Flow: Helping you automate workflow

Systems such as nervous, circulatory etc can be the glue that makes everything work well. This is the platform doing its job at regulating everything. Connecting things and making sure any one extension doesn’t blow things up. Acting as an engine for connectors and workflows like Shopify Flow.

If you look deeper at Shopify and the Stripe platform, you see a variety of surfaces that offer extension points… e.g. the Stripe Dashboard, or the Shopify Admin. These surfaces have specific extensions with rich context. They offer embeddable UI points, with building blocks to have your extensions fit in (e.g. components that feel consistent for the users of that surface). These extensible app platforms have a variety of surfaces. In Shopify, you can ship an app that enhances the Admin for merchants, or Checkout for users, and more.

NOTE: I was particularly excited to see that Stripe is using the open source remote-ui library that we created and use in Shopify:

“remote-ui allows you to create custom component APIs in JavaScript that can be used to render UI from a context other than the UI thread, like a web worker.” Love seeing this awesome work get used in more embedded developer context! https://t.co/9ICRNWRtb8

— Dion Almaer (@dalmaer) May 24, 2022

Ok. So, at this point, Shopi, is looking great with awesome clothing, a bionic arm, Tony Stark’s heart, and AR glasses. But you may want to customize EVEN more. This is where custom storefronts come in for Shopify. You can tie into the nervous system still via API (GraphQL or REST), but the body can be entirely different… with you building many more layers as you eschew the defaults. It doesn’t even have to be a binary choice… you should be able to weave together custom and the core headful experience.

I look forward to a future where merchants can customize their own Shopi to be exactly what they need, working with the foundations that Shopify gives them, and the creativity and skill of the developer ecosystem to provide apps, themes, and custom storefront work.

I’m also excited to see more extensible app platforms such as Stripe’s, and we share ideas and technology to raise all of the boats.

Extensibility is going to go from changes to the appearance, to bionic improvements, to providing genetic modifications.

Agency developers are underrated

April 21, 2022

You hear about the developer who created Wordle, or who went on to found a large company, or contributed an open source project to the commons. You don’t often hear about the agency developer, and they are both important and often on their own journeys.

The Value of Agency

Agencies, and consultants, are out there helping make businesses a reality. They deliver expertise when it doesn’t exist in house. They quickly expand the workforce and when done right, leave employees better equipped for growth.

By working at multiple companies in a domain, they can bring learnings, just as employees do when they change companies as they journey through their career.

I have found that high quality agencies are true experts who have bet their business on your platform, understand your competition, and know what your users really want. They build true empathy on what it takes to be successful.

If a platform company doesn’t have programs that include agencies as a tier one cohort they are probably doing it wrong. Ask yourself:

  • Am I training the developers at agencies to have a great understanding of what my platform or product offers? If they are asked, or are given freedom to choose, what solution to build on… would they choose you?
  • Are these developers external advocates in the community? Is there a community for them to show their chops, be rewarded for their knowledge, and celebrated?
  • Does the business team at agencies understand your offering and are you supporting them so they can be an extended sales force for you?
  • Do you have agencies not only servicing customers directly, but also through self-service opportunities (e.g. building apps / extensions / themes)?

At Shopify for example, our agencies are a vital part of our ecosystem, working with us on a joint mission to be merchant obsessed as a way to improve commerce for all. As I have dived into the ecosystem I am constantly finding agencies who deeply understand commerce and our platform, and are at the heart of delivering for our merchants to make their experiences unique and high quality.

We often talk about learning the tech, and the product, but learning commerce is an important key, and agencies have a lot of that knowledge. And once you understand the domain, competition, and environment, opportunities are unlocked.

The Entrepreneurial Path

Many of the solo or small team entrepreneurial developers that I have met came from a past life working at a merchant or at agencies. That was the training ground for their knowledge.

I have seen some common patterns when getting to know our developers, including one very strong one:

“I worked at an agency working on commerce sites for $YEARS. I started to notice that several of our clients were asking for $FEATURE, so I decided that I would build a Shopify app that delivers the feature and enables any merchant the ability to unlock it!”

— Pat

This takes so much risk away from your app development. For one, you can do work for clients directly to prove things out, and this gives you a direct line to a customer with the clear need (else they wouldn’t pay!) Then by working with other merchants you can learn what needs to be customizable, and then when ready an app version unlocks scale. It’s nice to get paid decent money from a merchant to do guaranteed work, and it’s nice to get money whenever someone installs your app.

This is yet another example of the power of de-risking app development with Shopify.

Thank you agencies, and those of you working at them. You are at the heart of it all.


Others in the series:

  • Tech writers are underrated
  • Project managers are underrated
  • QA engineers are underrated.

Next Page »

Primary Sidebar

Twitter

My Tweets

Recent Posts

  • I have scissors all over my house
  • GenAI: Lessons working with LLMs
  • Generative AI: It’s Time to Get Into First Gear
  • Developer Docs + GenAI = ❤️
  • We keep confusing efficacy for effectiveness

Follow

  • LinkedIn
  • Medium
  • RSS
  • Twitter

Tags

3d Touch 2016 Active Recall Adaptive Design Agile Amazon Echo Android Android Development Apple Application Apps Artificial Intelligence Autocorrect blog Bots Brain Calendar Career Advice Cloud Computing Coding Cognitive Bias Commerce Communication Companies Conference Consciousness Cooking Cricket Cross Platform Deadline Delivery Design Desktop Developer Advocacy Developer Experience Developer Platform Developer Productivity Developer Relations Developers Developer Tools Development Distributed Teams Documentation DX Ecosystem Education Energy Engineering Engineering Mangement Entrepreneurship Exercise Family Fitness Founders Future GenAI Gender Equality Google Google Developer Google IO Habits Health HR Integrations JavaScript Jobs Jquery Kids Stories Kotlin Language Leadership Learning Lottery Machine Learning Management Messaging Metrics Micro Learning Microservices Microsoft Mobile Mobile App Development Mobile Apps Mobile Web Moving On NPM Open Source Organization Organization Design Pair Programming Paren Parenting Path Performance Platform Platform Thinking Politics Product Design Product Development Productivity Product Management Product Metrics Programming Progress Progressive Enhancement Progressive Web App Project Management Psychology Push Notifications pwa QA Rails React Reactive Remix Remote Working Resilience Ruby on Rails Screentime Self Improvement Service Worker Sharing Economy Shipping Shopify Short Story Silicon Valley Slack Software Software Development Spaced Repetition Speaking Startup Steve Jobs Study Teaching Team Building Tech Tech Ecosystems Technical Writing Technology Tools Transportation TV Series Twitter Typescript Uber UI Unknown User Experience User Testing UX vitals Voice Walmart Web Web Components Web Development Web Extensions Web Frameworks Web Performance Web Platform WWDC Yarn

Subscribe via Email

Enter your email address to subscribe to this blog and receive notifications of new posts by email.

Archives

  • February 2023
  • January 2023
  • September 2022
  • June 2022
  • May 2022
  • April 2022
  • March 2022
  • February 2022
  • November 2021
  • August 2021
  • July 2021
  • February 2021
  • January 2021
  • May 2020
  • April 2020
  • October 2019
  • August 2019
  • July 2019
  • June 2019
  • April 2019
  • March 2019
  • January 2019
  • October 2018
  • August 2018
  • July 2018
  • May 2018
  • February 2018
  • December 2017
  • November 2017
  • September 2017
  • August 2017
  • July 2017
  • May 2017
  • April 2017
  • March 2017
  • February 2017
  • January 2017
  • December 2016
  • November 2016
  • October 2016
  • September 2016
  • August 2016
  • July 2016
  • June 2016
  • May 2016
  • April 2016
  • March 2016
  • February 2016
  • January 2016
  • December 2015
  • November 2015
  • October 2015
  • September 2015
  • August 2015
  • July 2015
  • June 2015
  • May 2015
  • April 2015
  • March 2015
  • February 2015
  • January 2015
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • July 2014
  • June 2014
  • May 2014
  • April 2014
  • March 2014
  • February 2014
  • December 2013
  • November 2013
  • October 2013
  • September 2013
  • August 2013
  • July 2013
  • June 2013
  • May 2013
  • April 2013
  • March 2013
  • February 2013
  • December 2012
  • November 2012
  • October 2012
  • September 2012
  • August 2012

Search

Subscribe

RSS feed RSS - Posts

The right thing to do, is the right thing to do.

The right thing to do, is the right thing to do.

Dion Almaer

Copyright © 2023 · Log in

 

Loading Comments...