[hibernate-issues] [JIRA] (HSEARCH-4847) Move getting started guides to separate documents

Yoann Rodière ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... ) *created* an issue Hibernate Search ( https://hibernate.atlassian.net/browse/HSEARCH?atlOrigin=eyJpIjoiOGIyZGU5... ) / Task ( https://hibernate.atlassian.net/browse/HSEARCH-4847?atlOrigin=eyJpIjoiOGI... ) HSEARCH-4847 ( https://hibernate.atlassian.net/browse/HSEARCH-4847?atlOrigin=eyJpIjoiOGI... ) Move getting started guides to separate documents ( https://hibernate.atlassian.net/browse/HSEARCH-4847?atlOrigin=eyJpIjoiOGI... ) Issue Type: Task Assignee: Unassigned Components: documentation Created: 01/May/2023 23:59 PM Fix Versions: 6.2-backlog Priority: Major Reporter: Yoann Rodière ( https://hibernate.atlassian.net/secure/ViewProfile.jspa?accountId=557058%... ) Because that’s apparently a best-practice to separate tutorials from reference documentation, to avoid overwhelming readers with a massive reference when they’re only after a short introduction. Todo: * Split the documentation * Move the asciidoc for “ Getting started with the Hibernate ORM integration” and “Getting started with the Standalone POJO Mapper” to separate directories/files in the source (we need two separate guides). * Adapt pom.xml to actually generate those documents * Adapt the distribution module to copy those documents (if it doesn’t already work; it may be copying all generated documentation already) * Keep a (very short) “Getting started” section in the reference documentation, which will basically be the first two paragraphs we currently have ( https://docs.jboss.org/hibernate/search/6.2/reference/en-US/html_single/#... ) , adapted to just point to the two getting started guides. * Make sure all the anchors we had in there will point to that “Getting started” section. * Convert links from the reference to the getting started guides (and vice-versa) to cross-references using xref ( https://docs.asciidoctor.org/asciidoc/latest/macros/inter-document-xref/ ). * Check the result * Check that the new documents (both HTML and PDF) are correctly included in the distribution ZIP. * Check that links from the reference to the getting started guides (and vice-versa) work correctly: * In the distrubiton ZIP (at least the HTML version; the PDF probably won’t work). * After being deployed to docs.jboss.org ( http://docs.jboss.org ) (not sure how we can check that; we don’t want to erase existing documentation during our tests…) * Remind Yoann to adapt the website to point to those docs when we next release Hibernate Search ( https://hibernate.atlassian.net/browse/HSEARCH-4847#add-comment?atlOrigin... ) Add Comment ( https://hibernate.atlassian.net/browse/HSEARCH-4847#add-comment?atlOrigin... ) Get Jira notifications on your phone! Download the Jira Cloud app for Android ( https://play.google.com/store/apps/details?id=com.atlassian.android.jira.... ) or iOS ( https://itunes.apple.com/app/apple-store/id1006972087?pt=696495&ct=Em... ) This message was sent by Atlassian Jira (v1001.0.0-SNAPSHOT#100224- sha1:07bd2b7 )