Work Proposal: Support for community content on farmos.org

Jobs Board
1

Work Proposal

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

Description

As a continuation of the farmOS.org Redesign, I have been working on adding support for tutorials and other community content on farmos.org, 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/farmOS.org 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.

Poll

Do you support funding this proposal?
  • Yes
  • No

0 voters

3 Likes
2

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.

2 Likes
3

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.

4 Likes
4

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 farmos.org is important enough, IMHO, iā€™m happy to support the cause as best i can, JG. Rock on, mate!

3 Likes
5

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.

Thanks!

1 Like
6

:+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

3 Likes
7

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:

Tutorials

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

How-Tos

  • 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
    • ā€¦
  • ā€¦

Reference

  • Data model
  • Development docs
  • Hosting (is the current hosting docs ā€œreferenceā€? or how-to? or a bit muddled?)

Discussions

  • 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 farmOS.org (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 farmOS.org 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:

3 Likes
8

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?

9

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
10

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
11

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/farmOS.org repo itself in this earlier topic:

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

1 Like
12

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 farmOS.org 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.

3 Likes
13

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:

3 Likes
14

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

2 Likes
15

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

I say, letā€™s put some collective moneys where our collective mouths are!

:money_mouth_face:

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.

Thoughts?

2 Likes
16

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ā€¦

2 Likes
17

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.

3 Likes