[
https://issues.apache.org/jira/browse/SOLR-12930?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16666149#comment-16666149
]
Cassandra Targett commented on SOLR-12930:
------------------------------------------
Sorry for the length of the comment, there are a few things I wanted to make
sure were clear, both in what I have been suggesting and what I know about the
realities of trying to publish some docs-something, no matter how casually we
try to do it.
{quote}I think the reference guide needs to be for end users and not include
things being discussed here...
{quote}
I agree, it should not be part of the standard Ref Guide. Also there are
release rules about VOTES to publish the Ref Guide (since it is an "official"
artifact of the project) that would be obstructions if we applied them to
developer documentation. A goal needs to be to remove as many obstructions as
possible - or at least not put them up at the start.
A sibling dev guide is exactly the proposal I made in my earlier comments and
in the example project I created.
The basic infrastructure I created in my small example project is mostly only
there if we want to publish an HTML version of a Dev Guide online, and not only
rely on developers to either load pages in their IDEs (which most committers
could be expected to do as a general rule) or have to go find the pages
somewhere in the tree in Github to look at them (which new contributors may not
know to do). A one-stop place for "everything anyone needs to know about
developing Solr", linked from the Resources page of the website, would be quite
helpful IMO to new potential contributors.
I think they _should_ be in asciidoc format, so all our docs are in the same
file format; it reduces context switching which would encourage participation
from everyone.
I have not been suggesting that we copy everything we do today for the Ref
Guide and do it for developer docs (or, I was attempting to specifically not
suggest that). If you look at the strawman project I made, it's not nearly as
complex as the Ref Guide. That comparison requires you to have a sense for how
the Ref Guide works, but it's basically just an ant target that downloads a
.jar and builds an HTML page in about 3 seconds. It's a lot simpler than the
Ref Guide process which includes a lot of page templates and nav building and
validation for correctness that we could forego for this case.
{quote}I don't think we necessarily need to have it all on one page, there
probably shouldn't be very many total pages...
{quote}
Regarding this point - just to make sure we're referring to the same thing, my
point about a single page was not that all the content lives in some single
huge file. That would be a pain to maintain and edit. The content should be in
multiple files that each discuss a specific area of development (setting up
your IDE, how to build, how to write tests, how to submit patches, etc.). The
idea of a single file was about taking all those smaller files we write and
_publishing_ them as a single HTML page that is the thing make public. This is
is done very easily with Asciidoctor
([https://asciidoctor.org/docs/user-manual/#include-directive]).
But, in case you meant having multiple HTML pages as the output - as soon as
you have more than one page, you need navigation between those pages. You don't
get navigation between pages without some work on our part to make it happen
(perhaps a page hierarchy, then you need clues for the user about where they
are in the hierarchy) and some of the complexity of the Ref Guide today is in
building the page navigation and you can only do that if you have a template
for the page so they are all the same...essentially the only way to get that is
to do something like Jekyll, which is why we have to use that today for the Ref
Guide. A single HTML page allows us to forget all of those concerns because the
nav - such as it is - is built into the side of the page during the build
process. We only need to make sure all the pages are included in the mono-page
using the include directive functionality I mentioned ^^.
{quote}At some point in the relatively near future, all git repositories at
Apache will be migrated from the git-wip system to gitbox
{quote}
The Gitbox transition is interesting in this context. One of the things this
change will do is make the Github repo the primary repository, which for us
today is a mirror of the ASF Git repo (our current ASF Git repo becomes the
read-only mirror). So instead of pushing our commits to ASF Git, we push them
to Github, and we pull new changes from Github. That opens up all of Github's
features which today we cannot use (a primary one being the ability to interact
with pull requests directly from Github).
For this discussion an interesting feature then would be the ability to use
Github Pages ([https://pages.github.com/]), which has deep Asciidoctor
integration and could be integrated into our project how we see fit. This gives
us _another_ place we could publish a Dev Guide, but that publication can
happen as soon as changes are pushed to the branch we would need to maintain
specifically for this purpose (I believe it has to be called "gh-pages"; a
workflow might be we make changes to master, then cherry-pick to this branch).
There's a little bit of complexity there in terms of changing our usual
workflows, but maybe that's worth it, because as I said in an earlier comment,
someone is going to have to push some sort of button somewhere to get any
content published out to the world (unless we don't do that and instead just
expect people find it in the source). Workflows are going to need to change in
some way anyway. It's just a question of which change we like the most.
> Add great developer documentation for writing tests.
> ----------------------------------------------------
>
> Key: SOLR-12930
> URL: https://issues.apache.org/jira/browse/SOLR-12930
> Project: Solr
> Issue Type: Sub-task
> Security Level: Public(Default Security Level. Issues are Public)
> Components: Tests
> Reporter: Mark Miller
> Priority: Major
> Attachments: solr-dev-docs.zip
>
>
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
