Refresh README.adoc and associated docs
sturtison opened this issue · 10 comments
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
That's sounds great 👍🏻
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.
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
- 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.
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.
Looking for the recommended way to show the my.email@example.com in the as-is block.
Looking for the recommended way to show the my.email@example.com in the as-is block.
Fixed.
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
Truly excellent work @sturtison and @ggrossetie!
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.