Funny you should mention!! Nowhere near complete or even “figured out” - but I started a branch to start thinking about this in 2.x:
Also, I’m realizing my use of the word “merge” in my ideas above is confusing at best, and misleading at worst. I’ll try to clarify soon… occupied with family stuff right now. 
Ok, here’s a bit more context to my thinking… hope this helps!
The content on farmOS.org right now can be divided into two categories:
I’d like to consider the 1.x documentation “deprecated” as soon possible, and be ready to make 2.x docs “canonical”. I’ve been working on bringing the 2.x docs up to parity with the 1.x docs, and as of right now it’s almost there! The “User guide” and “API docs” are the only two pieces that aren’t covered yet - and there may be opportunities to rethink our approach to those now, too (per @symbioquine and @paul121’s comments above).
Setting those aside, and stepping back, I think one of the basic questions here (in this forum topic) is: “how does a visitor get to both 1.x and 2.x docs from farmOS.org?”
@jgaehring’s idea to pull everything together into farmOS.org via Gatsby is a good one!
I feel like it makes more sense to bring these all under one umbrella with Gatsby.
…
it provides consistency across the board, which might be more of a cosmetic concern, yea, but I think branding is important in the documentation, too
I agree having everything under one umbrella would have a lot of benefits. And so I’m mainly thinking through: “how do we do that incrementally?”
The reason I always try to think incrementally is because I know that these kind of community based efforts can take time, and this one in particular has a lot of aspects to it, so it helps to break it down into bite sized chunks. Not only does this decouple the different aspects/goals, it also makes it easier for others to jump in and help in smaller ways.
So, I’m wondering if we can make that the end goal, but actually start by going in the other direction first: separate things. Then each step in the process becomes simpler.
Going back to my first point above (“the content on farmOS.org can be divided into two categories”), if we were to start by moving all the 1.x-specific docs out to a separate hostname (eg: https://1x.farmOS.org), then we would be starting with three distinct and very well-delineated sites:
Alongside that “split”, @jgaehring could start a brand new repository for farmOS.org, with an initial focus on:
At the end of this first pass, we have a beautiful new farmOS.org, with links to the other docs (for now).
All of that could be achieved pretty quickly, I think, and would leave us in a great spot. So in the off chance that things get delayed, or the next stage takes longer, at least we have a beautiful new site, and everyone can find the docs they need. It’s not the “one umbrella” with a unified brand yet - but it checks all the critical boxes.
Then, @jgaehring can proceed foreward with the Gatsby aggregation initiative, and this can happen at whatever pace it needs to. All the little details can be figured out, with no pressure or rush to get the new design out - because that part is already done! It’s just a matter of aggregating/organizing the content.
So, I think we end up at the same end-goal. The only difference is we do it in two steps.
And maybe both of these things happen in rapid succession! But knowing how community driven project like these go, there’s a good chance things will take longer than expected. So my thought is: why not decouple those two pieces, so we can get the “redesign” (eg: make it look pretty) done first. So first impressions are 
!
One related idea I feel is important to share, which is informing some of this thinking, is that in my ideal future, farmOS.org would not include 1.x docs at all! I want to say goodbye to 1.x - and get to a point where we don’t even need to talk about “1.x vs 2.x” anymore. So one of my hopes is that the “Gatsby aggregation” only pulls in the 2.x docs (and docs for Field Kit, Aggregator, etc etc). So that’s also part of my reasoning behind splitting 1.x out to https://1x.farmOS.org entirely. If we plan for that future, then we can just “retire” the old farmOS.org repository altogether! Perhaps even move it to GitHub - farmOS-legacy/farmOS.org: This is the code that runs the official v1.farmOS.org website. as part of the first pass…
In some ways I see this as an opportunity to “close the chapter on 1.x”. If you look at my whiteboard sketch above with that in mind it might make more sense. 
Done! Inline user guides
Love all these ideas, @mstenta! With one small “but”:
[…]
Ummmm… Could it? 
I guess this is where we differ in how we estimate the work being portioned out. I see the design aspect being the lionshare of the custom work, whereas I see the technical work as being the more plug-n-play aspect. Gatsby offers a lot of superpowers, with it’s plugins for using multiple git repos as sources, etc, and that adds a certain irreducible complexity, for sure, but on the whole I’m not too worried about how that will work.
I think you’re idea of incremental development is spot-on though!
Perhaps we could go back to the roadmap I proposed above, with 4 major milestones:
I think we could certainly tease this apart further and think about the ordering. I guess implicit in the original concept is that we would migrate the old docs from MkDocs to Gatsby, and the bulk of that work would be in just reproducing the markup. I guess if we were ready to scrap the old docs sooner rather than later, we could, but I guess I’m not so sure that’s so feasible in, say, the next year. So let me come back to that. I think we can definitely put the community features on pause, unless someone wants to take ownership of that portion. Then the next question is, really, do we want to prioritize the rebranding, or the documentation first? Like I said, I think the documentation part is the easy stuff, just plugging together the different repos and figuring out a structure (subdomains vs subdirectories, etc). Then the rebranding should be considered the big chunk, imo.
So really I guess our major decision right now is, do we want to just roll out the documentation using an off-the-shelf Gatsby theme, of which there are plenty? We could keep them on a separate site, not worry about migrating any of the markup for the old site, work on the long and slow process of rebranding, and by the time that’s done, we can move the 1.x stuff over easily (w/o porting the markup), or ditch it, if that’s the preferred path. Or something along those lines?
Lemme know what you think.
So based on my questions above, I’m wondering about this as revised milestones going forward:
One last thought that came up in our team call…
Perhaps we should start thinking about this in 2 parts/repos:
This creates a nice separation, allowing for additional implementations, easy migration, and the opportunity for separate maintainers to take ownership of separate content.
Edit: One more benefit could be making it easy for the inline documents as a part of a self-hosted farmOS instance, like @Symbioquine is advocating for.
Haha I’m glad you emphasized that. I totally agree - didn’t mean to downplay/underestimate the effort there.
- Aggregate documentation for 2.x
- Rebranding
I wonder if we could consider swapping these two? farmOS 2.x is coming fast! It would be awesome if we could launch it with a rebrand at the same time.
I love this idea! Especially the idea of having a repo specifically for “blog” content, which we could assign maintainership to, to others in the community who want to help! Having all these pieces in separate repos is really nice in that way.
Seems wise just to keep the effort low on the 1.x side… leave the stuff that’s 1.x-specific in its current mkdocs format - just copy it into a new repo, hack up the branding so it’s clear that it’s for the “old 1.x farmOS”, and publish under 1x.farmOS.org.
@Symbioquine Yea I like that approach… I want to put 1.x behind us (maybe before we’re ready to haha), and it simplifies the requirements for a redesign if we don’t need to consider it.
Ok, so I think I’m going to chunk out these first two milestones listed above as a work proposal in a separate topic (per the process I outlined in Community Governance).
I will try to limit the scope of that proposal to the MVP of the Gatsby site and pulling in the 2.x docs (using the farmOS/farmOS#2.x branch as source) as a proof-of-concept that the gatsby-source-git plugin works as intended.
Meanwhile, should we continue the discussion here of how to migrate hosting, arrange repos, move project documentation into those projects’ corresponding repos, etc?
Some specific questions to ponder:
Those seem like the most pressing concerns, assuming we’d still like to coordinate the redesign with the launch of 2.x-beta or 2.0 proper. We can also discuss the blog and other community content if someone wants to take ownership of that.
I think we can cross some of these bridges when we get to them… we have some nice automation set up to auto-publish docs.farmos.org right now via GitHub Actions, so I’d want to make sure we have the same level of ease in a Gatsby-aggregated approach.
How do we want to orchestrate moving docs for the Aggregator and Field Kit into their respective repos, similar to how @mstenta has done for the farmOS docs?
The Aggregator docs are already in their own repo (just in a README.md now):
We do need to figure out the User Guide… which currently has both farmOS and Field Kit info in it.
At what point do we want to move the User Guide into a separate repo? (plus lots of other related considerations around the maintenance of that repo)
This needs more dedicated thought. We will have a 1.x User Guide, which I think we can just set up as a legacy site on 1x.farmos.org or something… and we will have a 2.x User Guide, which we are talking about building directly into farmOS itself: Inline user guides
That doesn’t include “contrib module” user guides, though, nor does it include Field Kit. So perhaps we should think about ways in which we can pull a “master” user guide together from multiple sources. This could include user guides from ALL modules (and other repos), whereas the “inline” guide would only have content for the modules that are enabled.