[
https://issues.apache.org/jira/browse/SOLR-10301?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16090862#comment-16090862
]
Cassandra Targett edited comment on SOLR-10301 at 7/18/17 12:29 AM:
--------------------------------------------------------------------
I would like to publish these meta-docs online somewhere, and I've thought of a
few possibilities:
* Manually convert them to HTML and put them on the website, maybe under
http://lucene.apache.org/solr/guide. Maintenance would be a (minor) issue here.
I really don't want to introduce a manual process though.
* Put them all in the Solr Wiki. I spent approximately 10 seconds thinking
about how much fun it would be to take AsciiDoc and jam it into MarkDown ...
and then discarded this idea.
* Publish them with the rest of the Guide. This is my preferred idea, so I
thought some more about it...
My proposal:
* Move the directory {{solr-ref-guide/meta-docs}} and its contents to
{{solr-ref-guide/src/meta-docs}} so they are found by the build process.
* Create a new page {{how-to-contribute.adoc}} that will have different content
depending on the format:
** HTML will use the {{include}} macro to pull the pages that are currently in
{{solr-ref-guide/meta-docs}} into one large page. An alternate idea would be
for them to be separate pages, but I rather like them being in a discreet
directory from the other content.
** PDF will have an intro paragraph and point users to the online version of
{{how-to-contribute.html}}. The reason I wanted to do this is the PDF is
already really, really long, and it feels like content that is better served
online instead.
* In the HTML version, the last item in the sidebar navigation will be a new
top-level heading "How to Contribute".
It would also be possible to only publish the content if the page is (or is
not) a DRAFT - but, personally I think it's fine to publish it in the "live"
HTML version.
If there aren't any objections or better ideas, I'll get this done tomorrow.
was (Author: ctargett):
I would like to publish these meta-docs online somewhere, and I've thought of a
few possibilities:
* Manually convert them to HTML and put them on the website, maybe under
http://lucene.apache.org/solr/guide. Maintenance would be a (minor) issue here.
I really don't want to introduce a manual process though.
* Put them all in the Solr Wiki. I spent approximately 10 seconds thinking
about how much fun it would be to take AsciiDoc and jam it into MarkDown ...
and then discarded this idea.
* Publish them with the rest of the Guide. This is my preferred idea, so I
thought some more about it...
My proposal:
* Move the directory {{solr-ref-guide/meta-docs}} and its contents to
{{solr-ref-guide/src/meta-docs}} so they are found by the build process.
* Create a new page {{how-to-contribute.adoc}} that will have different content
depending on the format:
** HTML will use the {{include}} macro to pull the pages that are currently in
{{solr-ref-guide/meta-docs}} into one large page.
** PDF will have an intro paragraph and point users to the online version of
{{how-to-contribute.html}}. The reason I wanted to do this is the PDF is
already really, really long, and it feels like content that is better served
online instead.
* In the HTML version, the last item in the sidebar navigation will be a new
top-level heading "How to Contribute".
It would also be possible to only publish the content if the page is (or is
not) a DRAFT - but, personally I think it's fine to publish it in the "live"
HTML version.
If there aren't any objections or better ideas, I'll get this done tomorrow.
> Create meta-documentation for how to write in asciidoc
> ------------------------------------------------------
>
> Key: SOLR-10301
> URL: https://issues.apache.org/jira/browse/SOLR-10301
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: documentation
> Reporter: Cassandra Targett
> Assignee: Cassandra Targett
>
> If we want to encourage new users and non-committers to contribute patches
> for the Ref Guide, we should document some basics on how to write in
> Asciidoc(tor) format, and how to install/use various tools to improve the
> experience.
> Some basic style guidelines may also be helpful, to ensure a consistent
> experience once docs are published.
--
This message was sent by Atlassian JIRA
(v6.4.14#64029)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@lucene.apache.org
For additional commands, e-mail: dev-h...@lucene.apache.org
