I’m hoping to resurrect this - I didn’t have time to help out with this last Summer, but I’m hoping I have some time now. There was an earlier conversation about what to do with developer docs back in Oct 2018, so I’ve also updated SOLR-12940 to use for creating the developer doc structure and getting moving forward with this.
I wrote some docs for how the PMC Chair does the stuff they need to do, so I’ll create a PR today that we can use for discussion about how we want to move forward. On Aug 16, 2019, 10:41 AM -0500, Jan Høydahl <jan....@cominvent.com>, wrote: > 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 <jan....@cominvent.com>: > > > > 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 > > >
