Continuing the discussion about our new dev-docs. Seems to be consensus of using Asciidoc.
I proposed three separate guides: > * /dev-docs : Common info i.e. Git, Pull requests, building, doing releases > etc. Publish in TLP site > * /lucene/dev-guide : Lucene-specific developer content. Publish in Lucene > web site > * /solr/dev-guide : Solr-specific developer content. Publish in Solr web site It is obvious that Lucene and Solr needs separate guides, but could we instead of adding a third TLP guide use asciidoc <include> for a few common .adoc in both the Lucene and Solr guides to avoid duplication? Don't yet know how the adoc -> html build would look like, there are several such tools out there and it is not given that we need to use the same tool as we do for the Solr RefGuide? Any thoughts? If we can conclude on the framework we could create JIRAs and start adding the skeleton… I also hope we can get some assistance from a Technical Writer in organizing the content, so we don't end up with one huge page or a random structure. -- Jan Høydahl, search solution architect Cominvent AS - www.cominvent.com > 17. jun. 2019 kl. 22:17 skrev Jan Høydahl <[email protected]>: > > Hi devs, > > Today we have mainly two sources of developer documentation (apart from > Javadoc and refGuide): > > * The websites. Very short instructions and linking to WIKI for in-depth > * The old Moin wikis at wiki.apache.org with more details > > Soon the old Moin wiki is being discontinued and I plan to migrate that > content to Confluence this week, see > https://issues.apache.org/jira/browse/LUCENE-8858 and > https://issues.apache.org/jira/browse/SOLR-13548 > > So the first step will be to just start using Confluence instead of Moin. > Help appreciated with the cleanup once the first migration is done in the two > JIRAs above. A LOT of the content in old WIKIs is outdated and a big cleanup > once this is in Confluence is highly needed! > > > Someone has also suggested to move most developer resources found in the WIKI > into the main GIT code tree, so you have it right there with your git clone. > What I want to discuss here is more detailed how that would look like and > what info to move over. > > One idea is to create one or more Asciidoc guides in the source tree, e.g > > * /dev-docs : Common info i.e. Git, Pull requests, building, doing releases > etc. Publish in TLP site > * /lucene/dev-guide : Lucene-specific developer content. Publish in Lucene > web site > * /solr/dev-guide : Solr-specific developer content. Publish in Solr web site > > These will be built with Jekyll by Jenkins, into nice HTML guides and > published to the web sites. > > There may be other ways to do this as well, such as creating a new git repo > for dev docs, but I think people have good experience from Solr's ref-guide > with keeping code and docs in sync. What do you think? > > -- > Jan Høydahl, search solution architect > Cominvent AS - www.cominvent.com >
