Where is a good place for documentation (i.e. Git-hosted pages) that is for target audience of Analysts and Curators?

[joewheaton]

What repo should we put documentation that is really targeted not a RAVE users, but at Project-Type curators (@Riverscapes/riverscape-project-curators) and Data or Project Curators? A few things triggered this:

1. @Cashe93 posted some useful instructions on SLAYR in this issue that we'll want to reference, but it really doesn't make sense to leave those buried in an issue thread that will get closed. It seems like the RiverscapesXML is not a bad place for that?
2. I was going to post some dataset curation instructions in RiverscapesData by copying our jekyll template into a docs folder there, but realized that we have that repo private and don't want it public necessarily (so can't used Git-hosted pages).
3. I also realize that much of the Technical Reference is stuff that may or may not be targeted at narrower audiences of fellow Riverscape Consortium contributors.

As I write this, I realize this might be more of a fundamental question for the Information Architect, but I thought you might have insights in the meantime.

This is a low priority, but just looking for some guidance. As we up our game and consistency (and get that Technical Writer on staff) I want to pay attention to where we "dump" useful content and references intended for different audiences. Thanks @MattReimer

[MattReimer]

Hmmm. Yeah. We're definitely starting to get a bit sprawl-y with our docs. I think the TL;DR comes from the wisdom of ancients:

Moving markdown files is easy; writing them is hard.
-- @MattReimer

I think @joewheaton you're right that an information architect would probably take inventory of all our sites and then come up with a plan where everybody can get to everything they need with the smallest amount of typing and clicks. This is why I don't want to get too caught up in rearranging deck chairs right now. Maybe let's just choose one of the following options and tell everybody to use it.

Here are some places we've scattered things:

• Rave Jekyll docs subsection. We store the (outdated) business logic writing docs in a subsection here so it seems like a natural place to put this.
• RiverscapesXML. There's no Jekyll site here but there is a docs folder with a bunch of markdown. People can see it rendered in Github and that works just fine. I'm happy to have people store docs here until we can find a proper home for it.
• RiverscapesData -- forget Jekyll for now. These are internal Docs anyway. You can just add markdown to the repo and github will render it for you. I like this option the best because it keeps a lot of markdown commits away from RiverscapesXML which means less noise in my day checking to make sure they're ok. Also there's no Jekyll build step where you have to worry if it's deployed. Just commit and it's there. Later we can just move the markdown into a jekyll site and it will be seamless.

We can also look into the wiki tab of Github but since we don't really use that anywhere else maybe that's just a new thing for no good reason.

One big guideline though:

• DON'T COPY DOCS, MOVE THEM. Otherwise we'll get totally mired in checking git dates to find the most recent changes or, worse, merge a bunch of conflicts when both have changed.

[joewheaton]

I think the TL;DR comes from the wisdom of ancients:

Moving markdown files is easy; writing them is hard.
-- @MattReimer

I think @joewheaton you're right that an information architect would probably take inventory of all our sites and then come up with a plan where everybody can get to everything they need with the smallest amount of typing and clicks. This is why I don't want to get too caught up in rearranging deck chairs right now. Maybe let's just choose one of the following options and tell everybody to use it.

Here are some places we've scattered things:

• Rave Jekyll docs subsection.

I am going to go with this for now. As you say, it can change later.

One big guideline though:

• DON'T COPY DOCS, MOVE THEM. Otherwise we'll get totally mired in checking git dates to find the most recent changes or, worse, merge a bunch of conflicts when both have changed.

Amen... for entire MD docs. Exception will be where markdown is stolen from within an issue thread. I think the issues should be preserved and an a reply added referencing folks to documentation that supersedes it.