Work Proposal: Support for community content on

Work Proposal

Title: Support for community content on
Submitted by: Jamie Gaehring
OpenCollective account: Jamie Gaehring - Open Collective
Cost: $1800
Completion Date: 30 Jun 2022


As a continuation of the Redesign, I have been working on adding support for tutorials and other community content on, but the work stalled out in mid-January as other work took precedence. A minimal amount of work is required for its completion, though the cost above reflects the hours I’ve already accrued, plus the remaining time that I’ve estimated.

The main scope of the remaining work includes:

  • Bug fix: Filter the “Home” path from the main navigation list
  • Feature: List and link to all content posts at /posts/index.html
  • Feature: Render Front Matter in the markup for each post (see below)
  • Feature: Install the plugins gatsby-plugin-sharp and gatsby-remark-images and enable images to be colocated with markdown files and referenced by their relative file address (eg, ![Title text](screenshot1.jpg))
  • Test & deploy to Netlify

The issue of Front Matter is one I brought up in a previous topic, and as I mentioned there, I will start with just a few properties that seem essential:

  • title: The title of the post, required for this first pass, though later if someone wanted they could generate a fallback from the first heading.
  • date: Official publication date, in yyyy-mm-dd format, also required.
  • author: We could have a default like “Anonymous” or “farmOS Community”, or just make it required. Later this could also link to other posts by the same author and/or their bio, GitHub, Twitter, etc.
  • slug: The last segment of the URL’s path (eg, intro-tutorial-to-farmos), probably optional since it would be easy to generate from the path of the markdown file or from the title property.
  • canonical: Optional, and strictly not necessary for this first pass, but it’s trivial to add a <meta> tag for this to the <head>, so we may as well.

Deliverables & Acceptance Criteria

  • Complete implementation of all features and bug fixes listed in the above description.
  • A prepared feature branch, containing those features, that is ready to merge into the farmOS/ repository’s main branch.
  • A test branch with a link to a source repository that contains sample content for testing, if content is not already available for publication.


Do you support funding this proposal?
  • Yes
  • No

0 voters


Presuming that delivery of funds would be predicated on delivery against spec -yes?

In any case, considering this GUT (Grand Unified Theory) of documentation, i would advocate for adopting its 4-square classification scheme for the different types of doc, i.e.:

  1. Tutorials
  2. How-To Guides
  3. Reference resources
  4. Explanations

However you might choose to implement it (tags, subdirectories, etc.), i think it is really helpful to be clear about the qualitative diffs across these 4 forms of doc, both in the authoring, and in the InfoArchitecture that should make them most easily accessible, depending on UserNeeds.


Yep! I’m happy clarify further if needed

Oh nice! I think I’ve heard variations of this but not sure I’ve seen it laid out so well before. In a technical sense, we could fairly easily create a category property in Front matter, we would just need to decide how to present those separate categories in the navigation and other UI elements.


Am happy to hear @jgaehring that you also find the GUT to be a useful framework. For my part, tho working w/in those guardrails is still a challenge, it’s the kind of challenge that makes communication more effective, so… Well worth the effort!

Yes! With >1 way to skin this cat, the important thing is that there be 4 mutually exclusive categories, and (i think, based on my own read of the GUT), that each doc artefact (independent of medium; video, text, Discourse post, etc… That’s another dimension of classification) should belong to n=1 of these categories. Tho this may seem an overly/ needlessly restrictive constraint, i have found (maybe you too, since our earlier collaboration on a related project suffered from lack of clarity about this distinction, as i recall it), it really helps to be perfectly clear about which of these doc-types you are working to produce.

Anyway: this issue of community contributions to is important enough, IMHO, i’m happy to support the cause as best i can, JG. Rock on, mate!


I won’t be able to make tmw’s dev call, unfortunately, but if folks attending want to use the opportunity to discuss and let me know if/when I should move forward with it, then I could start on it as early as next week.

I know we typically wait to do a final vote on these things until the following monthly call, the next of which is slated for July 13, but I had a sense that there active efforts to begin drafting some of the first content that might be ready by the end of June, roughly, so I’ll leave it up to others to decide if the approval process should be expedited. I can adjust the completion date according based on that decision, probably just need to know 2 weeks in advance of whenever it needs to be deployed.


1 Like

:+1: I support this proposal!

I don’t see any mention of theme/design type work here, just curious if this is something to consider. Not suggesting any major changes but want to make sure the current state is flexible with different types of media in community content. For example being able to embed a video, maybe position images left/right? I’m not too familiar but this might be more dependent on what gatsby markdown already does/does not support


I also support moving forward with this! Maybe we give folks until tomorrow to weigh in otherwise - and then :rocket:

@walt I love this. When you shared this in another thread a few months back (forget where), I watched the video and got inspired to map farmOS’s various resources into those four quadrants.

This is roughly what I came up with:


  • Getting started with farmOS
    • Basic concepts / how to think about it (brief, link to data model etc)


  • How to map locations
    • Assets as locations
    • Mapping tools
    • Navigation
  • How to log events
    • Standalone logs

    • Assigning logs to users

  • How to manage users
  • How to collect sensor data
  • How to install modules
    • Core modules
    • Contrib modules
  • How to host farmOS
  • How to set up a development environment
  • How to build a custom module


  • Data model
  • Development docs
  • Hosting (is the current hosting docs “reference”? or how-to? or a bit muddled?)


  • Forum
  • Issue queues

The above is a mix of mapping our existing resources (data model, dev docs, hosting docs, forum, issue queues) and also brainstorming ideas for the blog.

It feels to me like the blog will be most useful for “Tutorials” (prescribed walkthroughs of general usage) and “How-Tos” (targeted guides for specific tasks). So perhaps these are the only two “tags” / “categories” we need to start with in the blog?

The “Reference” stuff belongs on (IMO), like we have now. And the “Discussions” (which notably in the link above are referred to as “Explanation” in the image, but “Discussions” in the video/presentation - which I think together describe their true purpose as I understood it: “explained/discussed/agreed upon knoweledge”) are already well established in the forum and issue queues.

The current User Guide on is a bit of the oddball in this. And that is exactly one of the great points made in the video/presentation - they are sort of a weird mix of “How To” and “Reference” at this point. Perhaps there are ways we could improve that, but it feels OK for now to live with. Maybe as the blog gets more developed a new pathway forward will present itself for the user guide. :person_shrugging:


Am happy to see this project go-ahead, as i believe this community can be a powerful driver of farmOS uptake, supporting content & success.

Moreover, @mstenta, it’s good to hear you talking about the GUT of docs in such appreciative & nuanced terms. I agree 100% with your interpretation & mapping of GUT concepts to farmOS realities & needs, with just one doubt regarding the following statement:

I wholeheartedly agree withe the first sentence (focusing more on Practical side of GUT’s y-axis vs Theoretical, is very much what we need!), but then regarding your 2nd sentence (italics mine), i think there is a 3rd category of “User Stories” that could add real value to the blog. I put that in quotes because, while that is a Term of Art with a more-or-less specific meaning among developers, it could apply more loosely to our blog. In fact, blogs being historically a 1st-person-subjective medium, the more anecdotal voice of a particular personality is not out of place there (esp. if it is properly labelled as being of UserStory type), and indeed the blog might be considered lacking something w/o content of this nature.

That being said, i see two valid arguments against UserStory inclusion:

  1. User Stories are clearly of the Explanatory (i.e. Understanding-Oriented) type, so if you want the Blog to contain nothing but Practical material (i.e. Tutorials and How-Tos), then the UserStory does not belong.
  2. This farmOS.Discourse.Group contains a fair bit of UserStory-type material, and though it is a natural environment for material of that nature to emerge, this does not mean such material can’t appear somewhere else, where it could add as much or even more value.

Finally: don’t know if i’m right about this, but i see the UserStory as occupying a unique intersection set between proper domains of Discourse and Blog. There might be a more-or-less natural flow of such content from the former to the latter; this could also be the case with content of Tutorial and How-To types, which flows could be more effectively facilitated via active curation and/or built-in InfoArchitecture (existing Categories & Tags don’t really address such GUT-based distinctions). Gotta think on this a bit more. Your thoughts?

Yes! Image embedding & placement can add great value to software docs… And as to video: this is a domain of considerable untapped opportunity. In fact i have seen some pretty decent How-To and/or Tutorial (tho more Explanatory) in certain YouTube videos, mostly presented by Mike… But it’s not so easy to find the relevant segments in these videos (timecoded links in the Description field on YT could help), nor even to find the videos via YT or Google search. Video deserves treatment as a 1st-class form of docs!

1 Like

I love this idea! I think “User Stories” is a perfect blog category!

User Stories are clearly of the Explanatory (i.e. Understanding-Oriented) type, so if you want the Blog to contain nothing but Practical material (i.e. Tutorials and How-Tos), then the UserStory does not belong.

I don’t think the blog has to be limited to “Tutorials” and “How-Tos” by any means. Nor does it need to be limited to “documentation” for that matter! I wonder: will we use it to announce events? Or important new releases? I suppose those things could be considered “documentation” too in a very general (grand unified) sense. So perhaps some of it is semantics. :slight_smile:

This farmOS.Discourse.Group contains a fair bit of UserStory-type material, and though it is a natural environment for material of that nature to emerge, this does not mean such material can’t appear somewhere else, where it could add as much or even more value.

Agreed! And whereas the forum is nice because it is very “loose” - anyone can post - and anyone can comment, “User Story” blog posts can be more curated, perhaps more in-depth, etc. They can be featured stories that bubble up from forum discussions we want to highlight.

And as to video: this is a domain of considerable untapped opportunity. In fact i have seen some pretty decent How-To and/or Tutorial (tho more Explanatory) in certain YouTube videos, mostly presented by Mike… But it’s not so easy to find the relevant segments in these videos (timecoded links in the Description field on YT could help), nor even to find the videos via YT or Google search. Video deserves treatment as a 1st-class form of docs!

Yes! I’m not sure if you were on the recent call where this came up, but I suggested that some blog posts could be primarily a video. But that whenever we do that we should also include a transcript of the video below it - for all the reasons you just described.

1 Like

Thanks for the feedback, everyone! I’ll get moving on these changes tomorrow and report on my progress by the end of the week. For now, I’m going to close the poll, since we’ve reached consensus.

Been meaning to get back to this, and I don’t intend go too crazy with the CSS, but it should be pretty easy to just set up images to display nicely as blocks between paragraphs. That’s how I do it on my personal blog and it requires no additional CSS or anything beyond normal Markdown syntax. I do tweak the max-width setting as recommended for the gatsby-remark-images plugin, but it is ultimately constrained by the max-width of its container, the .post element.

As for video embeds, that depends upon how we specifically choose to do embed them, but assuming that may require raw HTML in place of plain Markdown anyways, I don’t see any major issues incorporating that into the blog template. This is once again where it will be nice to be able to specify the template for each source, so if there are styles that we prefer for tutorials as opposed to documentation, that can be done indpendently. I’m also sure there are plugins that could add some pizzazz w/o too much additional effort, but I don’t intend to look into that right now, mostly because I don’t think we have a clearly defined alternative design, at least not at this point.

I should also point out that, if anyone wants to start a more permanent repository for the blog content, or fork the example repo I started, they can then start experimenting with different tagging structures in the Front Matter. I left a little more explanation for how this repo connects to the farmOS/ repo itself in this earlier topic:

And the even earlier discussion we had about possible ways to structure those tags:

1 Like

A day later than hoped, but the core deliverables are ready, as outlined below. I know @mstenta is taking time off for another week or more, and as far as I know there’s no content waiting to be published, so I don’t see any rush to sign off on these acceptance criteria, but I wanted to make sure to hand it off before this holiday weekend here in the states. Perhaps we can review it at the next Monthy Call on July 13th.

Deliverable 1: Implementation

These can be viewed in the preview deployment:

There are some decisions that need to be made about what to name the index page and where to place it in the navigation, but that can all be easily configured.

With regard to the Front Matter properties that can be added to markdown posts, I’ve started us off with the following:

  • author: Defaults to "the farmOS Community".
  • canonical: Optional.
  • date: Required.
  • slug: Defaults to the directory name if not provided.
  • title: Required, unless a an h1 is provided in the markdown.

The only absolutely required property is date, because I don’t see a good way around this to provide some minimal degree of sorting, as well as a means of approximating how up-to-date a post is. Also note that the first h1 element in the markdown, regardless of whether it’s used as the title in the main heading, will be stripped out of the markdown itself. This behavior could be modified or made configurable, but for a first pass this seemed like the most sensible choice. The Front Matter properties as a whole can be structured however we wish, they just need to be changed in the GraphQL type definitions provided to Gatsby.

Deliverable 2: Feature branch

I’ve opened a Pull Request for these feature from the blog branch from my own fork, ready to merge or accept additional commits:

As I noted there, I don’t think it should be merged until we have some content ready to publish and make some time to decide on some of the configuration choices I mentioned under Deliverable 1. If nothing else, we need to set the source repo and branch once we know what those will be.

Deliverable 3: Source repository

I’ve created a bare-bones source repository and testing branch, here:

The main branch is even more bare, with only 3 files: a license, a README and a .gitignore. No config.yml file is needed, since I don’t think we want to manually place each individual post in the navigation menu, and the rest can be configured from site-data.js in the repo. If we want, we can transfer farmOS-community-blog to the farmOS GitHub organization, or create a new one, or whatever we like, so long as we update site-data.js accordingly.


Nice! ticks all the boxes, and opens the space for the flow of UGC to begin.

Now: I’ve read the conversation thread on PR#49, and- much as i agree with @mstenta comments there about the need for standard Information Architecture details (i.e. URL composition, categories, tags, etc.) to be fleshed-out, i also agree with @jgaehring about prioritising development of content- what i would call a Minimally Representative Sample, having a modicum of diversity -before building out any such IA guardrails.

Right! So, if the road map for development on this front is to go like that- (1) Content (2) Configs for IA (3) merge the PR -then the Q becomes: How to achieve forward motion on that next step 1?

:+1: that agenda item, JG. If there’s one thing i’ve learned the hard way, it’s that the “Build It And They Will Come” philosophy simply does not apply in this particular problem space. That being so, i think the dev team will do very well now to develop a strategy for facilitating flow of content from beyond the dev team itself, if this blog really means to attract and retain a diverse community of users.

ps: Congrats, JG, on getting 'er done before holiday weekend. Happy Independence Day :sunglasses:


Hear hear! Great job @jgaehring! And agreed that once we have some content we can think about categories etc. :rocket:


MRS, I love it! And thanks, Walt, appreciate the feedback. :relaxed:

I say, let’s put some collective moneys where our collective mouths are!


This brings us back to @mstenta’s original 4 post ideas, from First blog posts brainstorm (dev call 2022-06-09):

No. 1 was intended to be a volunteer project by the core team, so I expect as a group effort it will move rather slow (unless there’s a near-ready draft floating around I don’t know about?). That’s fine though, b/c it’s kinda intended to link to the other articles anyways, and that just gives more time for those to be developed.

The last three, however, I think are prime candidates for posting some kind of bounty in the Jobs Board category. Especially No. 2, which I might give a provisional click-baity title of “3 Ways to Get Started with farmOS that John Deere Doesn’t Want You to Know!” I think it’s pretty straight-forward, and can lean heavily on existing docs, especially w/r/t the last option (self-hosting). So maybe $75 or $85 USD for a 1000-1500 word article? Then we can see how that goes, and decide if it makes sense to fund any of the others that way?

And I think the most important thing here is not to treat any of these articles (or the $'s funding them) as something we “gotta get right the first time” or something altogether too precious. They don’t have to be the canonical reference point for anything, and will inevitably be superseded by more current and relevant posts as time goes by. That’s the whole rationale for this project, as far as I see it. And if we get people engaged and thinking about this stuff, while also throwing some bucks their way for the effort, that’s money well spent, even if it’s not exactly the written output we were aiming for.



As a way to kick-start this process, @jgaehring , i think your idea of posting a bounty as reward for contribution(s?) of content on certain topic(s?) earmarked for priority treatment is a good one -certainly worth a try, i think, in the context of a time-limited campaign.

I do wonder how such a campaign would be managed -i.e.: Like a competition (the usual meaning of bounty), as in: first one to deliver on-spec nabs the reward? Who decides if it meets the spec, and how? What if it delivers well against some criteria in the spec, but not all? If for example that topic of ‘3 ways to get up&running in farmOS’ (paraphrase) were to be the priority, and were to attract two submissions oriented to 2 different approaches (i.e. Farmier vs self-hosted)… How to handle that?

Such questions notwithstanding, i think that- absent some real “marketing muscle” applied to this campaign -the problem of dealing w/ multiple overlapping submissions is not so likely to happen (tho it would be good in a way if it did!). Plus, given the modest value of the proposed bounty (say $80 / 1250 words would be little over a penny a word), i don’t forsee a feeding frenzy over this, in any case, so…

Bottom line: i second the motion of your proposal. Let’s run 'er up the flagpole and see how she flies…


Those are very good points; just by “outsourcing” some of the content creation we still have to deal with oversight, which could potentially become even more work. But I also agree with your assessment that we’re not likely to see an high stakes bidding war for these bounties any time soon. In that sense, I think this is a great opportunity to answer some of those questions while things are low stakes, so long as we acknowledge this is just a work-in-progress governance model and that there will be flaws. Hopefully the fixes will be made apparent in the attempt.