asciidoctor/asciidoctor-browser-extension

Refresh README.adoc and associated docs

sturtison opened this issue · 10 comments

sturtison commented

Could I help you with your plugin by suggesting some changes via a draft PR to refresh the docs?

See draft PR #649

See latest draft page here: https://github.com/sturtison/asciidoctor-browser-extension/blob/docs/issue-648-refresh-docs-draft/README.adoc

  • Streamline for a person who is a foundational user of AsciiDoc and installing browser extensions
  • Reorder sections (essential towards the top, advance towards the end)
  • Rename the hacking.adoc to CONTRIBUTING.adoc in line with convention and the README.adoc
  • Footnote the Firefox bugs and add their last updated date.

Proposed TOC for the Asciidoctor Browser Extension

  • Get started
    • Install from the browser extension webstores
    • Install in Chrome, Chromium, Brave or Opera
    • Install in Firefox
  • Configuring extension options
    • Chrome, Chromium, Brave or Opera
    • Firefox
    • Common options
  • Local installations
    • Chrome, Chromium, Brave or Opera
    • Firefox
  • Contributing
  • Changelog
  • Copyright

Thank you for a great plugin.

Edits: Add link to the draft PR #649, to the latest page

ggrossetie commented

That's sounds great 👍🏻

sturtison commented

This does not provide a walk through like #528 however it does lead the different reader groups through the install in more detail.

Some adoption road bumps have been:

  • The browser choice (Chromium or FireFox)
  • Confusion between the Browser's settings for the extension, and the Extension Settings.
  • Enterprise users having to have the plugin distributed internally by IT support before use.
sturtison commented

Squashed and rebased on main.

  • add asciidoctor icon to introduction
  • add mini-menu
  • add alt-text to webstore images
  • use URI attributes for most URLs
  • be inside the mind of a foundations learner of:
      - AsciiDoc
      - Installing browser extensions
  • reorder sections
      - Essential material to the top
      - Advanced material to the end
  • add sections
  • expand option descriptions
  • advise read of data leaving the computer with Kroki.io
  • remove closing steps that aren't steps and convert them to closing step list comments.
  • replace some admonitions with focused text
  • chromium-browser-list attribute for consistency
  • refresh learn more URLs with docs.asciidoctor.org links
  • add known issues section for the Firefox bugs and update their last updated status
  • more detailed guide to open the Chrome extensions dialog
sturtison commented
  • Example
    Two images: active, inactive
  • New to AsciiDoc
    Tiny introduction to AsciiDoc and link to asciidoc.org etc
    ** Example from this page
    The previous section in AsciiDoc - Shows use of attributes etc.
    ** Try it yourself
    How to reproduce the images shown in Examples.
sturtison commented

The URIs for the images will have to be changed if the PR is accepted as they refer to the raw.githubusercontent on the forked branch.

  • 👍1
sturtison commented

The URIs for the images will have to be changed if the PR is accepted as they refer to the raw.githubusercontent on the forked branch.

Fixed by @ggrossetie to be :url-asciidoctor-sc-image: https://cdn.jsdelivr.net/gh/asciidoctor/asciidoctor/screenshot.png in features.adoc

mojavelinux commented

Truly excellent work @sturtison and @ggrossetie!

mojavelinux commented

To ensure that docs changes get published right away (instead of nightly), you may be interested in setting up the deploy-docs workflow. See https://github.com/asciidoctor/asciidoctor-pdf/blob/v2.3.x/.github/workflows/deploy-docs.yml for an example. I've already set up the secret for that workflow to use.