farmOS.org Redesign

Community
1

Hi all!

The idea of redesigning the official farmOS website has been kicking around for a while now, and with the approach of farmOS 2.0 and other pertinent needs, we’ve begun to talk more seriously about what we can do. But we can’t do it without the support of our community, so we’d like to hear your ideas and suggestions for how we can improve it.

We’ll be discussing these improvements in our next Monthly Call on October 14th, but we’d love to hear your feedback here as well. Below I’ve outlined our tentative plan for this development, as well as how we plan to fund it, but everything is up for discussion.

If you have a moment to read through the plan and leave a comment on what changes you’d like to see, what difficulties you may have faced with the current site, as well as your ideas on new community features we could build into this plan, it would be greatly appreciated.

I look forward to reading your comments!

~ Jamie

Roadmap

There are 4 major milestones for the redesign:

  • Migrate from MkDocs to Gatbsy (required before other milestones)
  • Community features & content
  • Rebranding
  • Technical Documentation

Only the first is required before any of the other work; everything else can happen independently and in a different order.

Migrate from MkDocs to Gatsby

This is a process I began on It’s My farmOS Day at the beginning of this year, but there’s still a good bit of work to be done. The idea is this will be sort of our MVP (“minimal viable product”) prior to embarking on other changes, which will rely on having a more robust Static Site Generator like Gatsby. More details on this in the GitHub issue.

Community features & content

This is the most exciting prospect to me, because we have a chance to rethink how community members participate in farmOS’s development and ultimate success. One way we’ve discussed this in the past is to breakdown

  • Official Guide & Tutorials: These would be the core documents for folks to learn how to get started with farmOS and maintain their records on an ongoing basis. These would have the highest expections for quality and relevance to a general audience. They would also come with the expectation that they would be kept up-to-date with the most current version of farmOS and Field Kit, and that translations would be provided wherever possible. It’s worth noting that @kirsten_mc has been spearheading the creation of new tutorials, so I’d love to incorporate those efforts into this milestone and see that they are compensated for their contributions.
  • Community Blog: This idea was proposed by @walt during It’s My farmOS! and I think has a lot of potential as an intermediary set of tutorials, recipes and stories, prepared by and for our users. They’d be “lightly curated”, as Walt puts it. Unlike the official guide, this content would be timestamped and not required to be updated, which I think gives a lot more latitude to focus on specific workflows and user scenarios that we can’t cover in the guide.
  • Forum: (ie, this forum) This is the space for the most informal community discussion, questions, opinions, etc. This wouldn’t be hosted on the official site, but we’d of course want to prominently link to it, somewhere in the main nav.

There are some other ideas kicking around that we could try to implement, like a dedicated section for feature bounties, more translation work of the website itself, etc. But I’d really like to hear other folks’ thoughts on what might be helpful to users new and old, as well as ways in which we can bring the community closer together to achieve our shared goals and have a bit of fun along the way. So once again, please comment below with your ideas!

Rebranding

This would be an overhaul of the general look and feel of the site to reflect the robust, reliable and industry-tested suite of software that farmOS has become in recent years. The existing site has served us well as a repository for the user guide and other community resources, but we could go a lot further to enhance the perception of farmOS both as a software product and as a community.

Documentation

An important aspect of any free and open source project is that anyone with the gumption should be encouraged to explore the code and modify and extend the software as they see fit. As the farmOS team becomes more and more engaged in the OpenTEAM initiative, this couldn’t be more important than it is now, in order to promote interoperability with other services and technologies.

The footprint of our codebase has also greatly expanded in the last couple years, with separate API’s for writing modules for both farmOS and Field Kit, as well as general API services for accessing farmOS servers and the Aggregator. Organizing the documentation for these diverse technologies into a single, coherent collection will be the top challenge of this milestone. Ultimately, though, if we’re successful in that effort, it should mean broader inclusion of partners and contributors to the farmOS ecosystem, and a greater range of services for farmOS users.

Funding

Of course these milestones will require the time and talent of developers and content creators, so we’d like to explore options for funding those efforts.

The Gatsby migration as well as the community features are the areas where I believe the community will benefit the most, so it seems ideal to crowdfund these milestones. Fortunately, we already have accrued a significant level of donations from our Open Collective, which I believe will cover the cost of the Gatsby migration at the very least, and probably a portion of the community features and content. Once we’ve assessed what other features and content we want to develop, we can launch a fundraising initiative to cover this additional development, perhaps with stretch goals to provide some flexibility.

The rebranding is an aspect I anticipate the community will benefit from to some degree as well, but as someone who gets a paycheck from farmOS development, I feel I stand to gain the most from other potential funders being attracted to the project in the future. I see this rebranding primarily as an investment in my own earning potential, so I’m happy to make this my contribution to the project.

As for the documentation work, I’m confident this can be funded through other channels.

Governance

Since a portion of this project will entail fund raising and the allocation of those funds, I believe its important to establish a policy of transparency about that process as well as some guidelines for how we can make important decisions collectively. This is where I’d most like to step aside and hear from other community members about what they expect in terms of governance, how best to be inclusive in this process and how to balance that with the practical goals of seeing this project to fruition. Again, let us know in the comments and/or join the Monthly Call on October 14th to let us know how you’d best like to see this project governed.

5 Likes
2

Migrate from MkDocs to Gatsby

@jgaehring @Symbioquine Another way to frame this may actually be: “Splitting the site into Mkdocs and Gatsby”

I’m using Mkdocs in farmOS 2.x to build ~~http://2x.farmos.org~~ https://docs.farmos.org already. So in a sense we aren’t getting rid of Mkdocs - just using it for the stuff it was intended for (documentation). Meanwhile we can use Gatsby to build the main farmOS.org site (which links to the docs, forum, etc).

So in that sense we’re just splitting the current site in two.

1 Like
3

Yea, that’s definitely one way to do it, although we may want to consider what benefits we could be losing out on (as well as gaining, perhaps) if we don’t have Gatsby for templating the 2.x docs. I suppose that’s a later consideration, though, and maybe a part of the rebranding effort.

1 Like
4

Quick update on:

I’m using Mkdocs in farmOS 2.x to build http://docs.farmos.org already.

I recently discovered the Mkdocs Material theme. :slight_smile:

It’s looking pretty good! ~~https://2x.farmOS.org~~ https://docs.farmOS.org

I’m leaning more towards suggesting we keep this as a separate site from https://farmOS.org itself. And when 2.0 is released, we move 2x.farmOS.org to docs.farmOS.org (this is done)

Decoupling the “docs” from the “website” is a good thing, IMO. And if we just link to it from https://farmOS.org it may greatly simplify what is necessary for the farmOS.org v2 itself. The focus can be on making it into a community portal, instead of trying to make it do everything.

One lingering question in my mind, if we take that approach: what about the docs for farmOS.js, farmOS.py, farmOS-map, Field Kit, and Aggregator? Right now those are all in the README.md files of their respective repositories. Maybe that’s enough, though, and we just link to those in the same way.

Also: what about the “User guide”?

We were talking about how the User Guide does need to be tied to the codebase, because as new features are added to farmOS, they need to be documented in the User Guide. Up until now, I’ve been doing those in parallel across two repositories (farmOS and farmOS.org). It might be nice to have it in the same repo. And I’d like to decouple that from the farmOS.org repo.

An interesting idea was proposed on one of the monthly calls…

Imagine if you could read the User Guide in farmOS directly. And… imagine if installing additional modules dynamically added to it. So you end up with a User Guide that is tailored to your particular set of modules. This would be really cool, I think - and I don’t think it would be too hard to achieve.

The drawback to this would be: in order to view the User Guide you would need a farmOS instance. Maybe in practice most people who need the guide already have farmOS, but I’m sure there are others who are considering using farmOS and having the guide available on farmOS.org helps to introduce them to it.

So… perhaps this is where the power of Gatsby can help us. :slight_smile:

Imagine: a farmOS.org Gatsby codebase that pulls user guide content from all the various other repos (farmOS itself + contrib modules + maybe Field Kit too?) and assembles it into a master guide. It might essentially be the same as what you would see in farmOS if you installed all modules (therefore adding all their user guides).

This could be very powerful! And would have some benefits:

  • Keeps user guide content tied to the repository it is relevant to (and therefore the version)
  • Keeps farmOS.org repo codebase relatively simple. It just needs to know about the other repos and have a way of pulling content in from them.
  • Allows tailored user-guides to be available directly within farmOS itself - which would ONLY include the information that is relevant to you. I imagine this would go a long way lowering the barrier to entry for some folks. Eg: your farm employees only see documentation for things that are relevant to them (perhaps with some permission/access control in the user guide content as well!)

Then, if the User Guide content is stored in separate repos, along with the other “documentation” like API docs, hosting guides, data model documentation, etc, it makes the farmOS.org codebase much simpler. Perhaps it would just have the community blog posts, as well as high-level pages like FAQ, quick links to other places (forum, chat, docs.farmOS.org), monthly call schedule, and a flashy homepage. :wink:

5

Not sure it’s the best strategy, but following the pattern, the libraries/client/aggregator could have their own Github-pages/mkdocs sites hosted similarly. e.g.;

Various docs could link to each other, but would generally be expected to have relatively low coupling.

2 Likes
6

That’s an interesting idea @Symbioquine! Just a network of separate Mkdocs instances, all auto-pushed and hosted via GitHub Actions + GitHub Pages. That’s really all we need for most “repo-tied” docs like these.

7

Yeah, it’s nice because it decouples them so, for example, Field Kit could build its docs with Gatsby if that made more sense. However, it also has the drawback that it might encourage an inconsistent look/feel over all the documentation and would involve some duplicate setup/maintenance for each documentation instance.

1 Like
8

Yea I’d say we try to maintain consistency as much as possible. I see farmOS.org as the place for more experimentation with “look and feel”, because it is really the focus of the “branding” initiative, and the documentation as more standardized. Based on what we have now in all the various README.md files I think Mkdocs works just fine.

My vote would be for the Material Mkdocs theme in green. :slight_smile:

9

I guess this is why I feel like it makes more sense to bring these all under one umbrella with Gatsby. There’s a little more upfront work to get Gatsby to do the task of aggregation of all the separate markdown files across separate repos, but there are handy plugins that should help with a lot of that. What’s perhaps most important, in my mind, is how this consolidates maintenance across all the different documentation repos. Instead of each repo being responsible for its own version of mkdocs, theming, hosting, etc, we can do that all in one place.

And, as @Symbioquine pointed out, 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. Partly because it makes the documentation easier to use and to find what you’re looking for, but also because it makes us look more established and professional. I believe that, in turn, will attract more and higher caliber contributions from community, as well as grant us more credibility from industry partners. I think that credibility is absolutely critical if we want farmOS to carve out a niche as the interoperable farm data store, and documentation is perhaps the most visible indicator of that.

Not that we have to do this all at once, but I think it’s sensible to aim towards these goals and strive to get there by increments.

2 Likes
10

As a prospective farmOS user and beginning farmer, I’d like to provide some feedback regarding the future website your 3rd milestone of rebranding. Not sure if that’s what folks are looking for here, but here it goes:

For future iterations, perhaps consider more of a conversational and “marketing” approach to the website, while reframing it with a clearer defined ‘farmer’ customer focus, and less of the programmer/developer, and product mindset.

When I go to the farmOS.org landing page, I like the initial overhead banner picture of the farmOS software, and I like the initial opening paragraph:

“farmOS is a web-based application for farm management, planning, and record keeping. It is developed by…” etc.

But after that opening paragraph, the site (at least on my smartphone) shifts to a very heavy computer programming vibe, as the next paragraphs (as well as other pages on the site) use a very tech-heavy lexicon that makes me think…eh, is this software and community really for me?

i.e.:
modular; extensible; server; native; progressive web application; code repository; forums; chat; open source; developing; Twitter; hosting.

I think farmer’s at large are still traditionally viewed as simple, honest, mostly conservative folk, who have a wide breadth of skill and knowledge and technical prowess, but still heavily retain that salt-of-the-earth, bootstrapping mindset.

Putting myself into that mindset:

When I hear ‘server’, I think:
“Let’s go eat at Waffle House”
When I hear ‘progressive’ I think:
“You mean main stream media propaganda? No thanks”
When I hear ‘developers’ I think:
“Not on my land!”
When I hear ‘user guide’ I think:
“Pshh! I used to fly military helicopters, how hard can installing and using this program thing be?”

Don’t get me wrong, I’m not a full time farmer, I don’t live in the Midwest, I’ve built pretty cool robots and have done computer vision in the past, and I am currently learning Python.

And I have TREMENDOUS respect for you and your project, and the hard work, leadership and character, wizarding tech skills, and collaboration you all have put into it.

But until maybe three years ago, I was still using a flip phone, had never needed or paid for a cable-internet package, and today I think about my “farm” and fencing, cover crops, and irrigation plans and seeds varieties, yada yada…ALL the dang time.

Knowing what I know as a mere farmOS community ‘lurker’, if farmOS were a product that I could pay for once and pick up in a Tractor Supply Co store, I’d probably grab that CD or USB or wifi device or whatever and install it on my computer.

But would any of my neighbors purchase it? Probably not, unless they have a Comp-Sci background.

I’d say farmOS is still a really tough sell for mass appeal to the average farmer, who are in their late 50’s and 60’s, if my memory serves me.

4 Likes
11

Love these thoughts @Kilt - and agree 100%.

I will admit that I have been intentionally slow about “marketing” farmOS up until now. It has been very valuable to target tech-savvy “early adopters” in the beginning, and farmOS.org reflects that. :slight_smile:

I think we’re ready for a facelift. Especially alongside the release of farmOS 2.0!

12

Thanks, Mike. Well, come to think of it, your choice in intentionally targeting tech-savvy users during these initial years for “customers” shows great wisdom and restraint: it’s probably way easier to refine the product and work out any bugs that way.

I certainly look forward to seeing the next iteration. There is going to be so much turn over in farms (in the US at least) over the next couple decades, and farmOS brings some exciting opportunities to help the next generation stay on top of things. Great work everyone!

2 Likes
13

Update: I’ve been slowly porting/updating docs into the farmOS 2.x repository. I just finished up the hosting/installing/updating docs. I outlined the remaining pages that need to be considered on farmOS.org in this comment: Consider merging 7.x-1.x documentation into farmOS repository · Issue #22 · farmOS/farmOS.org · GitHub - It’s not that many!

I think the big next step will be updating/migrating the “User guide” section to the farmOS repo. After that, it should be pretty easy to reorganize the remaining farmOS.org pages into a simple community portal as an easy next step (and perhaps explore the more advanced Gatsby aggregation ideas soon after?)

1 Like
14

Sounds good!

Just so I understand, is the plan to host migrate 7.x-1.x docs to the farmOS repo as well? And do you have a URL scheme in mind for how to distinguish 1.x docs from 2.x?

Looking forward to resuming the Gatsby work after I move. Promised myself I’d have a proposal together before the March Monthly Call!

15

Not sure yet! But some ideas are starting to crystalize… curious to hear what folks think!

My main focus with what I did last night was to a) copy and update all the “hosting” related documentation into the farmOS 2.x branch, and b) review and outline what other pages/sections are currently on farmOS.org that will need a new home…

There are a few different goals/interests here… all very interrelated, and I’m trying to think about them with an eye towards incremental rollout. They are:

  1. Making it easy to “start fresh” on a redesigned “community portal”.
  2. Ensuring that 1.x and 2.x docs are available/accessible to those who need them.
  3. Preserving history.

The path to achieving all of these (incrementally) is starting to fall together in my mind… and hopefully it compliments the ideas you have for the redesign (and makes it easier)!

Regarding #1 (“making it easy to start fresh”) - wouldn’t it be nice to start a brand new main branch for the new farmOS.org site from scratch, without any shared history or baggage from the existing 7.x-1.x branch? We could start fresh with a nice homepage, and pick and choose which pages/sections from the old branch make sense to keep (and would have some liberty to adapt them). This would mainly include the general community pages/sections, I think (eg: docs/community/*, docs/donate.md, etc). But we could leave behind anything that is really specific to 1.x or 2.x of farmOS…

… which leads into #2 (“ensuring that 1.x and 2.x docs are available”).

As a first step, 2.x docs are going to be available at https://docs.farmOS.org (previously https://2x.farmOS.org). This is built directly from the /docs directory of the farmOS 2.x branch, so it can be maintained and updated alongside farmOS itself as it changes. So that covers “making 2.x docs accessible”… (as an incremental step, at least)

As for 1.x docs, I think that’s still an open question in my mind… do we create a new https://1x.farmOS.org as a “snapshot” of the current farmOS.org repo’s 7.x-1.x branch? Maybe we remove a bunch of the misc content, so it’s just the user guide and hosting info (assuming everything else gets recreated in the new portal or ported to farmOS 2.x)? And add a message to the effect of “this is for the OLD version of farmOS, click here for latest docs”? That could be an easy way to have an “archival” 1.x docs site, when 2.x becomes the officially recommended version. And this could be done incrementally if the redesign comes together before 2.x as well, I think. Open to ideas on this!

In either case, one thing I would like to do (which shouldn’t really affect any of the above decisions), is merge the existing history of the farmOS.org 7.x-1.x branch into the farmOS 2.x branch, in the same way that I will be doing with the 7.x-1.x branch of farmOS itself. And to be clear, by “merge” I mean the following:

# Perform final merge of 7.x-1.x into the current branch using the "ours"
# strategy to discard all changes from 7.x-1.x. This serves to indicate
# that 7.x-1.x has been incorporated into the new main line, thus preserving
# its full history, commit counts, contributor/author info, etc.
git merge -s ours --allow-unrelated-histories origin/7.x-1.x

That’s what these two issues are for, specifically:

The reason to do this is to achieve #3 (“preservation of history”). I see these two 7.x-1.x branches as legacies of farmOS’s past, and are valuable to preserve in their own right, even though they will no longer be maintained. By merging them both into the 2.x branch of farmOS itself, we preserve them in the core Git tree, and we also get the benefit of including all the contributors to farmOS.org in the farmOS GitHub contribution summaries - which is good for a lot of reasons, IMO. It serves to celebrate everyone that has contributed to farmOS and farmOS.org during the 1.x life-cycle, while at the same time creating a nice clean break and redefining farmOS.org’s new role moving forward (the new “community portal”!)

I made a quick whiteboard sketch to try to convey how this looks from a high level in my mind:

Screenshot from 2021-02-26 14-25-19
Screenshot from 2021-02-26 14-25-19932×698 198 KB

  • The RED “farmOS 2.x” represents the 2.x branch of farmOS - It will become the new default branch.
  • The GREEN “farmOS 7.x-1.x” represents the 7.x-1.x branch of farmOS - When it comes time to make 2.x the default branch, it will be merged into 2.x. But notice that I did leave a little green line coming off of it, which represents some minimal support for dependency/security updates for folks still on 1.x (TBD how long we support that).
  • The MAGENTA “farmOS.org 7.x-1.x” represents the 7.x-1.x branch of farmOS.org - This can be merged into 2.x at the same time as the GREEN merge. We could potentially DELETE this branch from the farmOS.org repository at that point. But perhaps we have another little magenta line coming off of that that represents the “archival 1.x docs” that I described above (or we create a new repo for that in the legacy GitHub organization).
  • The MAGENTA “farmOS.org main” represents a proposed NEW branch of the farmOS.org repository, which is a clean start (notice how it does not branch off of the 7.x-1.x line, but starts as a new branch with a unique history and initial commit).

What do y’all think?

1 Like
16

I’ve gotta check myself out for the weekend shortly and don’t have time to read through everything in your last comment carefully, @mstenta; however, if I get the gist of what you’re saying, I’d like to point you to the last comment in this issue:

That’s the git strategy I’m imagining for how to start fresh (#1) while also preserving history (#3). And I think the strategy is also compatible with #2, but I need to learn more what you have in mind for that. If you have a moment, take a look, discuss with others, and I’ll pop back in to see where you’re at come next week.

1 Like
17

Awesome! Yes! I think these are all compatible and complimentary pathways! I’ll try to get a few more ideas into words … have a great weekend! :slight_smile:

18

I still favor the strategy of making the user guide portion of the documentation self-hosted. i.e. Making it part of farmOS itself… If we do that as part of a final 7.x-1.x release, that documentation could live as long as there are any 7.x-1.x installations online.

Another advantage of self-hosted documentation is that it works in offline/air-gapped/limited-connectivity scenarios. I’m imagining a farm/homestead which has off-grid power and a sketchy internet connection but runs farmOS on a local network.

Obviously the current version of the user guide should also be available online at farmOS.org.

GitLab does an excellent job of this sort of thing. If you host a local instance all the “help” links and stuff reference self-hosted copies of the documentation - which besides working “offline” also is nice because you can tell you’re looking at the documentation for the version you’re actually running.

2 Likes
19

+1 to this!

Drupal 9 has a core concept of Help Topics. It’s an experimental module right now - but will soon be stable! These are fairly targeted towards general Drupal administration, but I think it would be possible to create dedicated sections for farmOS topics and “hide” what isn’t needed for normal users. They should be theme-able as well.

A nice feature is that they can be translated with the existing Drupal localization service. But perhaps a downside of this is the topics need to be written in twig files. Markdown would probably be best… but maybe a script could auto-generate the twig files from markdown??

2 Likes
20

Perhaps we should open a separate topic for this?

2 Likes