farmOS blog/tutorials

Community
1

On yesterday’s monthly call, we talked about starting a repository to host a farmOS “blog”, primarily for posting tutorials, workflows and “recipes” etc as a supplement to the user guide.

For 2.x, I think the consensus is to limit the user guide to the most essential functionality of farmOS, without too much elaboration, so it is less susceptible to breaking changes with newer versions. Then the tutorials, which can be timestamped and also indicate the version they were written for, can augment that with greater details, but aren’t required to be maintained as rigorously as the user guide.

With the new farmos.org I’m building with Gatsby, which can pull from multiple source repositories, it makes sense to me to have a separate repository for this content, which can be managed independently by the community, separate from the project repositories, like farmOS and farmOS.py, but also separate from the Gatsby repo itself, so the content could be ported to other sites, if and when the need arose. I think it would be nice, too, if other community members wanted to take ownership of it and maintain it, so it’s not all on me or whoever else maintains farmos.org to also shoulder responsibility for the content as well.

So would it make sense to start a repository now, so we can add it as a source repo to the new Gatsby site, and open up the potential to start taking contributions? Perhaps we could even shoot to get this up and running by the time farmOS 2.0.0-beta is ready for release, since that will mark a point when we start bringing on beta testers, who might want to use and/or contribute to that content?

CC’ing @mikefarms who seemed interested in this possibility when we discussed it yesterday.

4 Likes
2

Oh, and a nice thought I had just now too… For the tutorials we can use branches or tags that correspond to different versions of farmOS and pull those in as separate sources… then we can have a toggle on each tutorial page if it has examples for older versions, kind of how Digital Ocean does:

Anyways, just a thought, perhaps for a stretch goal.

1 Like
3

@jgaehring, thanks so much for following up. I would love to help with this, maybe with a quick test tutorial on a topic that’s come up while I’ve been coming up to speed (mail server!). Some questions:

  • Any good tutorial has the ability to embed pics/screenshots - should those go in the same directory as the md file or a subdirectory with a name convention? If possible, I’d recommend each tutorial just be in a flat directory on its own in the repository.
  • What tag structure do you want? Should I use this Gatsby explanation as a basis for our convention? What would you like to see?
  • How would you like me to check this test tutorial into Github? Which repository should I add to and create a pull request for? Or do you want me to create a test repository of my own and send you the link first?
2 Likes
4

:100:

Yea, I like having a directory for each tutorial, and keeping those all in a content or tutorials directory. That’s how I do it for my own blog, basically a structure like this:

content/
├─ how_to_create_a_log/
│  ├─ index.md
│  ├─ screenshot1.jpg
└─ how_to_create_an_asset/
   ├─ index.md
   └─ assetpage.jpg

Then from within content/how_to_create_a_log/index.md you would just reference the image like this:

![Title text](screenshot1.jpg)

For that to work, all I need to do is install the plugins gatsby-plugin-sharp and gatsby-remark-images and add them to gatsby-config.js with the proper settings. I was planning to do that eventually and it should be pretty straightforward.

We’ve already got support for Front Matter, which is the type of header you see in that Gatsby tutorial on tags. I think title, date and path (or slug) are good variables to start with. I would probably hold off implementing anything to display or use a tags variable, at least while we’re still prototyping this, but you could still add tags to the Front Matter of any post for the time being and it wouldn’t hurt anything (basically they’ll just be ignored). Other useful variables could be something like post-type to indicate if it’s a tutorial, blog post, news item, etc; a thumbnail var that can be set to the filename of an image in the post’s subdirectory; a projects var that could look something like this:

projects:
  - name: farmOS
    versions:
      - 2.0.0
      - 2.1.0
  - name: Field Kit
    versions:
      - 0.8.2
      - 2.0.0-alpha.1

Really no limit to the custom vars we could use, but it will be important to settle on some kind of conventions.

We don’t have a repository set up for this yet, but if you want to start playing around with it, feel free to start your own! If other folks are on-board with it, we can discuss making it an official repo, or figure out where else we want it to live long-term. Once you have some content to test out, I can create a branch in the Gatsby repo, add your repo as a source, and set up a preview deployment for testing it out.

2 Likes
5

An update on my part:

I’ve made some progress in the last couple days adding a second source repository to the new website I’m working on for farmos.org. Still a work in progress, but the preview is live.

Obviously there’s plenty more work to be done. It’s still just a skeleton around the documentation pages, without a real home page. There are lots of little technical issues to resolve, but imo, the biggest issues are all a matter of design decisions, like how to structure navigation between the different sources etc.

Most pertinent to this topic, I still need to integrate Front Matter into how the site map, page layouts and navigation are built. That capability’s there, the plugin’s already installed, now I just need to put it to use. That will have to go hand in hand with decisions about what the Front Matter should contain, which is really a blank slate, but should be consistent. As I said above:

So yea, I noticed @mikefarms and @Farmer-Ed have brought this up in Sensor Graph OK, but Sensor Data field empty, which is great to see!

If folks have other feedback to provide, please don’t hesitate to drop your comments below.

2 Likes
6

@jgaehring It was good to listen in on the call today. As you have seen I tend to document the farm tech projects I’m working on to my Blog, its for my own future reference as much as anything else. I’d be happy to copy some across when your Repo is ready. I’ll have a few more to do anyway as I’ll soon need to migrate to 2.0.

2 Likes
7

Awesome, and thanks for offering to share that content, @Farmer-Ed. I’ll keep you posted when we’re ready for that.

I’ll also make sure to include some sort of canonical property for Front Matter, too, and provide a link back to your blog for any material you share.

2 Likes
8

Ok, so a big step towards making it a reality, today we just launcehd the new farmOS.org!

It’s not a whole lot different, but the significant aspect of this is that we now have the ability to feed content to the site from separate source repositories, as I mentioned at the top of this thread. No such blog/tutorials repository exists yet, but it we should certainly move forward with creating one in the new year, perhaps during the next monthly call, or perhaps through a separate discussion in the farmOS community Jitsi room.

3 Likes
9

Just want to let folks on this thread know we’ll be discussing these ideas on Wed’s community call:

3 Likes