[Meta] Doc Enhancements Wishlist

[debadair]

This meta-issue is a collection of the various issues we have open regarding non-content doc enhancements:

• Doc infrastructure changes: build, validate, automate
• Interactive page widgets
• Doc architecture and design

There's some overlap and interaction between the different types of enhancements, so listing everything here for the time being.

Doc infrastructure changes

Build and validation

• Make doc builds more modular Make doc builds more modular #249
• Separate repos for doc infra and generated docs Repo size growth #153
• Add validation step for identifying unresolved attributes Doc build should show error when asciidoc attributes are not resolved #220
• Add a check for pages deleted in newer versions (automate redirects?) Add a check for pages deleted in newer versions #17, Add a check for new and deleted pages #1825
• Automatically generate previews Generate previews for books affected by documentation changes #483
• Enable comments on previews Enable annotations on doc previews #1211
• Support per-page diffs in previews Preview tool could have per-page diffs #1089

Rendering

• Add tooling to generate "jump" lists Add tooling to generate "jump" lists #324 closed
• Improve the rendering of multiple callouts Improving the layout of multiple callouts #265
• Render AsciiDoctor "thematic breaks" Allow horizontal rule in docs #1130
• Support embedded videos Embedded videos #995

Alternative outputs

• Offline docs (Docker image for ECE/air-gapped networks that is self contained)
• PDF docs (archive EOL docs) Build PDF version of docs #61
• Blog posts (uploadable HTML) Add a --blog option  #10
• Deploy pre-release Cloud doc builds internally Deploy pre-release Cloud doc builds internally #766
• Fix building docs on Windows Fix building docs on windows #1111

Automation and tooling

• Automate screencaps dev-#860
• Automatically rebuild affected docs with the shared attributes change Documentation build should be aware of changes to shared file attributes #1180
• Automatically rebuild old docs when version list changes Rebuild old docs when the version list changes #59
• Automate bumping doc versions Automate bumping doc versions #253
• Run release builds remotely Run release builds remotely #337

Interactive page widgets

• Copy as curl should support configuring the Elasticsearch host (and Cloud) Copy as curl should support setting the Elasticsearch host #335
• Add "copy code" functionality for command examples Add "copy code" functionality for command examples #319
• Add "Copy for Powershell" Add "Copy for Powershell" for Windows/Powershell users #210
• Disable invalid options in the version select box Disable invalid options in the version select box #291
• Add widget for displaying platform-specific instructions Create linked-tabs widget for displaying platform-specific instructions #260
• Add a documentation feedback link to each page Enable documentation feedback links #681
• Make Edit link more prominent and consider adding link for creating GitHub issues [Discuss] Make it easier for users to report and fix doc errors #1244
• Enable pop-ups for glossary terms. Inline pop-ups for glossary terms #1212

Doc Design

• Doc {re}design dev-#705
• Deprecated stuff should show up as deprecated in the TOC Deprecated stuff should show up as deprecated in the TOC #325
• Temporary CSS fixes CSS Fixes for the Docs #229
• Inconsistent style in definition lists Inconsistent style in definition lists with multiple paragraphs  #126
• Search titles
• Automate inserting " ... to learn more about X, see X-ing in the Y book."
• Support improved/customized landing pages: Observability, Clients Allow Customisation of Elasticsearch Clients Landing page #1114 client, Kibana, etc.

[kellyemurphy]

@debadair can we add "Get feedback on pages" under the interactive widget? A 👍 or 👎 would be a good start, but a small text box that opens with the 👎 would also be nice.

[nrichers]

@kellyemurphy @debadair I opened an issue for adding a feedback mechanism and linked to it in the root comment.

[aravindputrevu]

Folks - I came to docs repo to raise the issue of documentation feedback on each page. Happy to know that, we already thought about it.

But saw it also got closed because, cloud addressed it using a different mechanism. But it still could be a great feature to implement. Are we still thinking about it?

[kellyemurphy]

@nik9000 could we get a feature where we can get keyword popups for glossary words? It might be helpful to have those definitions in-line rather than having to navigate to a separate page and back again.

[nik9000]

I think an inline glossary would be really useful. I'm not sure how to do it in a friendly way, but it is worth thinking about!

[debadair]

@aravindputrevu Cloud is blazing the trail, but the intent is that once they have something that's workable we can use that mechanism across the docs.

[aravindputrevu]

Yeah sure. This is one constant request from community to enhance the docs experience and take feedback on how far a chapter solve their problem.

[alaudazzi]

@aravindputrevu that's one of the priorities in our Cloud doc roadmap. Check #26 for more background.

[szabosteve]

@debadair Can we add "Enable support for mathematical formulae" under "Rendering"? I've already opened an issue: #1765

[debadair]

Closing in favor of tracking the individual issues on a project board. See also #1340 and #1343.