Should we consolidate and move Technical Documentation away from riverscapes.xyz to tools.riverscapes.net/developers

[joewheaton]

@MattReimer, @jtgilbert and @philipbaileynar, when @MattReimer provided the helpful list of resources for Samuel (I stole it and posted at Riverscapes/RiverscapesXML#479), that highlighted something really annoying to me. Our different websites are not clear on who the audience is. Here I want to focus on documentation that is targeted at developers and curators (i.e. us and a few close firends). Almost everything @MattReimer referenced was in GitHub repos, but the actual website stuff (i.e. documentation for developers) is unhelpfully spread out between:
https://riverscapes.xyz/Tools/Technical_Reference/Documentation_Standards/Riverscapes_Projects/
https://rave.riverscapes.xyz/Technical_Reference/business-logic.html
http://brat.riverscapes.xyz/Documentation/Standards/

I would like to propose that we start a new "Developers" docs folder to host a website that would be tools.riverscapes.net/developers, and I presume posted at: https://github.com/Riverscapes/riverscapes-tools/tree/master/packages as Riverscapes/riverscapes-tools/tree/master/packages/developers/docs so it works like the others?

All this would be is a sub-site or web pages targeted at our developers. Part of what is motivating this is that as I go through the Riverscapes.xyz site, and the exercise for Aida, I realize that:
a) the site needs to be much more targeted at a general audience and all the "content" there is way over most people's heads.
b) the site may shift away from
c) we don't want to direct a bunch of general traffic in to a place where we have a bunch of in the weeds documentation (might also be a deterrent from our developers writing more imperfect, but helpful documentation.

Thoughts? @MattReimer if you're okay, can you stub me out a spot and we can follow same publication strategy (i.e. commit to docs branch) and then I will take a stab at moving content around and over.

[MattReimer]

This is the ongoing struggle.

a) the site needs to be much more targeted at a general audience and all the "content" there is way over most people's heads.

Agreed

b) the site may shift away from

???

c) we don't want to direct a bunch of general traffic in to a place where we have a bunch of in the weeds documentation (might also be a deterrent from our developers writing more imperfect, but helpful documentation.

I agree that development docs are not appropriate for general audiences. I also want to make sure that a consideration of where to store the developer docs is the distance between between it and the code. In general I want the docs for the tool to be in the same repo as the tool itself and be versioned along with the tool so we can all be a little more confident that the docs we're looking at match the version of the tool we're looking at.

• riverscapes-tools is entirely about one specific brand of python tools that work with GDAL. It doesn't really have anything to do with BusinessLogic.
• I agree that rave.riverscapes.xyz is maybe not the best place for XML docs but we're already using the GH-Pages of RiverscapesXML to host the XML itself so....

I'm going to think on this a little. @joewheaton maybe let's discuss this a little more so I can be sure I understand the plan.

[MattReimer]

Actually now with the new GH-Actions (Which I didn't have when we started this whole thing) we might be able to move all RiverscapesXML docs into that repo and publish it there. Might be a good candidate for our first Gatsby docs site too.

I'll have to think on this a little.

[jtgilbert]

From the perspective of coming in as a new guy again and working on both development and documentation it would be really nice to have them in a non-public facing site like this. And I agree that we need to think about the audience of the sites and separate out the elements of the tool sites that are for consumers vs. producers/developers.