‘Writing an extension’ documentation updates

[holly-cummins]

Description

I’m creating this work item to hold some of the content strategy discussion for improved extension documentation. We know we want to make it easier for people to start writing extensions and find out how to do common tasks (like writing a dev service). However, we should think carefully about how to structure this extra content and where it goes, so we don't just end up with a sea of words that ends up being even more confusing.

Proposed content plan

tentative! WIP!

See the 'gaps' section below. I think we want to fill in something for every gap, but we need to decide where things go.

Analysis

Assets we have

• My first extension guide
• A walkthrough of writing an extension to log to Amazon cloud watch, which is an excellent general tutorial about writing an extension
• Deeper reference guide
• Extension metadata documentation
• Blogs about how extensions can help with byte-code rewriting and other similar use cases:
  • Stripping out methods which have a problematic annotation
  • Resolving an annotation conflict by transforming breaking annotations into happy ones
• Presentations
  • Holly and Georgios’s from JNation, slides and video
  • Roberto Cortez’s deck
• A cute animation of build item resolution
• Holly's Minecraft demo
  • Source code
    • Quarkus insight
    • Short video

• "How to join the Quarkiverse" docs, particularly the checklist

Places we can put information

There’s some overlap between this and the ‘what’ list, but here I’m trying to focus on ‘where’, from an information architecture perspective.

• Guides
  • Dedicated extension content
  • Relevant content in other guides, such as the extension metadata documentation
• Quarkus Hub pages
• Quarkus blog
• Personal and external blogs

Types of documentation

The diataxis framework can help us think about the types of content we want, although we may want to go slightly beyond it with personal stories.

• Documentation
  • Tutorial
  • Reference
  • How to
  • Explanation
• ‘Case study/example’ blogs (for example, the Amazon cloud watch logging blog. I guess these are somewhere between tutorials and how-tos?

Gaps we have

• “My second extension” tutorial that goes past "my first extension" and covers the most typical extension scenarios (dev service? additional bean items?)
• List of ‘common reasons you would want to write an extension’
• List of common extension tasks (dev service, rewrite byte code, etc) with links to a “how to”, indexed by the ‘problem being solved’ rather than the ’solution technology’ → FAQ (frequently asked questions) documentation for extensions #42520
• How to write a dev service (calling this one out specifically since it’s an extra-big gap and @maxandersen tripped over it the other day) .. one question is what non-silly container we might want to include - hello world?→ Add "how to write dev services" documentation #42535
• “How to find out how to find out,” (eg ‘if you have a problem, browse the build items, because they’re our SPI’)
• Some items in the list of all build items are missing Javadoc entirely, and in some its truncated because of a publishing issue, which we should fix since they're our SPI (Broken and missing Javadoc for some build items on https://quarkus.io/guides/all-builditems #37290)
• A list of FAQs → FAQ (frequently asked questions) documentation for extensions #42520
• Content on how Quarkus works, as its relevant to extension writers
• Extension maturity model (this is in a few videos, but not published in written form) → Add explanation/concept for extension maturity model #42446
• “What is an extension” (at the moment we link to https://quarkus.io/faq/#what-is-a-quarkus-extension but it’s a bit tactical. I think @insectengine and Jeff Beck might have been looking at this, Documentation on how to use extensions (as a user) #27946)
• Documenting your extension (Antonio G mentioned he struggled with this and called it out as a gap. I've done a bit to improve it, but probably not enough). -> https://hub.quarkiverse.io/documentingyourextension/

It’s not exactly a gap, but the SEO, structure, and general usability of the hub.quarkiverse.io docs for Quarkiverse authors

This is more of a personal goal, but I'm including it here for completeness, since I think our strategy should include personal and 'neutral' content:

• More leverage of the Minecraft demo
  • Blog about it
    • Adding a dev service → https://www.youtube.com/watch?v=90FEj1zqjWQ
    • (and a blog about that)

Related issues

• Just make the tooling do the right thing, so we need less documentation
• Bug corrections and improvements to “my first extension” guide, cc @gsmet
• Javadoc problems in the list of all build items (Broken and missing Javadoc for some build items on https://quarkus.io/guides/all-builditems #37290)

Extension template issues

• New extension template creates integration tests, but they are not run - or referenced in the top-level pom.xml #29158
• Include README.md in extension template #30306

Epic items

(this section is auto-generated - manual edits will get lost)

• #37216 builidng my first extension missing test result in failure
• #37290 Broken and missing Javadoc for some build items on https://quarkus.io/guides/all-builditems

[quarkus-bot]

/cc @MichalMaler (documentation), @ebullient (documentation), @inoxx03 (documentation), @michelle-purcell (documentation), @rolfedh (documentation), @sheilamjones (documentation), @sunayna15 (documentation)