Community Documentation


#1

Hi @gordonb,

I was speaking with @david at a UAT event last week about documentation and we are beginning to think that a sort of “orientation guide” could be helpful. I’ve found that this has been an issue for newcomers to UAT interested in hacking the food computer with us.

Information like getting started with the food computer project, where to go for X in GitHub, and further explaining the architecture are three items we initially think would help others orient themselves as to how to get involved. Maybe this information could be a mix of technical and layman’s?

If this sounds like a good idea to you and OpenAg, @david and I can get started going through the GitHub, forum, wiki, etc. and put together questions/next steps we have.

Thoughts?

(@pauanta I think you may be interested in this thread)


#2

I think this is a good idea.

It would be great for folks to chip in on this thread and help develop an outline of topics we should cover.

What might work well in the long run is a GitHub repo full of markdown files. We could have it automatically generate a “guide” website, hosted at openag.media.mit.edu/guide (for example). Anyone could help write the guide by submitting a PR. (Our first go at this was a wiki, but it got swamped with spam. This is better.)


#3

I’m a newbie here, waiting for the PFC 2.0 to come out before jumping in, but documentation/tutorials is something that I’ve been thinking about. I’ve been a long-time interface designer and my wife is a graphic designer and we’d be happy to chip in to create user-


#4

Oops. Hit Enter by mistake. Anyways, what I wanted to finish with was to say that we’d be happy to help designing the documentation/tutorials. I could also make 3d models of everything if that’d be helpful.


#5

As a newbie, this would be very helpful


#6

Here are a few things I’ve been thinking of for the v2 docs:

  • Getting Started
  • A build guide
  • Downloading/running a recipe
  • BOM
  • API guides
  • API cookbook
  • CAD files
  • Links to all the repos/docs for those repos
  • [+] technical architecture

What else have we been missing?


Spanish translate
#7

@adrianlu thank you for including me, yes indeed, I am very interested in this topic.

@gordonb to your list, if you want people to get into the details, hack it and develop new features, I would add a key element: technical architecture of the solution (at least, a high level description or overview).

Let me share my recent experience: one week ago, I decided to create a database (sqlite3) to store the status of the actuators and the points of the sensors every X time (let’s say, every 10 minutes), so then I can play with this data. Although I am not an expert in Python and OOP, past days I spent some time surfing the different pieces of code (grodaemon, server, bot, communications, actuator, element, sensingpoint, …) and I understand many things, but I am missing a few ones that are relevant, and don’t understand others (for example, there are two logs - grodaemon and grostatus - that my FC is not using) and in the absence of an architecture overview, I do some trial and error, and so far, it’s been error (I did something that the UI can’t read the values of the sensors anymore, so I had to flash again the image and reinstall the SD card). This was not a big deal but I lost time.

BTW, funny comments in your code (I did exactly the same when I developed software in the 90s). Again, happy to help.


#8

Hi @gordonb,

I’ve met a few others interested in hacking the food computer in the Bay Area and we’re starting to form a consistent group of attendees. We’d like to get started helping out with documentation but are wondering what will be happening with the v2 release. What would you recommend we do in the coming months in terms of documentation? One thing I’ve identified as potentially useful is an FAQ.

As a documentation update on my end, I’ve been working on updating Urban AgTech’s website to include some information that will help orient newcomers to the FC project and how to get started hacking it locally with our group in SF. From the past three hack nights, I’ve found most newcomers come to first learn more about what a food computer is. Inevitably, they get super excited about the project and want to participate. Hence the question above. Do you have any suggestions on how our work can tie into the overall Getting Started doc?

I think once we have this information organized, our group can get our hands dirty in the other docs.

Hope all is well on the v2 push!
A

CC: @david


#9

A heads-up to everyone on this thread. I’ve set up a new Dokuwiki on a staging server and am starting to work on the next-generation documentation portal for the Food Computer. DM me if you want to help, and I’ll create you an account.


#11

The new wiki site (based on Dokuwiki) is now live. There is lots of new documentation, and lots more still to do. Sign up for an account and help improve it! http://wiki.openag.media.mit.edu/.