Proposal: Collect MVP code & docs into one github repo


#1

@Webb.Peter What do you think about setting up a github repo for collecting the MVP code and documentation all in one place? The idea would be to organize what you’ve got now to lay the foundation for making changes and improvements in a way that’s easier to keep track of going forward.

It sounds like @webbhm would prefer not to be on the hook for maintaining the MVP repo long-term. So, perhaps I could help you set up a code and documentation repo under your github account.

I can help you get the repo started, and I’d also be interested in helping transcribe your existing documentation from the google doc & powerpoint stuff into markdown documents in the github repo.

[ edit: If you like the general concept, let me know, and I’ll follow up with more details about how we might get a github workflow up and running.]


#2

I thought that is what we had with GitHub.com/futureag
/mvp has the code

/blog contains the documentation wiki

Do you have something else in mind?


#3

@webbhm, The link you gave goes to a 404 page. It looks like there’s an extra “tu” in there. Also, the futureag/blog repository appears to only have some placeholder files from an unfinished website project. I’m not sure what you meant about a wiki–maybe I’m overlooking something.

When I’ve done MVP troubleshooting sessions in the past here on the forum, I usually refer to the links at the top of this forum post: $300 Food Computer - MVP. That post gives 14 links to videos, slide decks, google docs and other resources to refer to. I’ve also seen other links floating around various forum posts and OpenAg wiki pages. This OpenAg wiki page (https://wiki.openag.media.mit.edu/mvp_1) has about 40 links that overlap some with the links in the forum post. I can imagine that it might be a little overwhelming for people to sort through all that and figure out which instructions are the authoritative and current version. My work-around has been to always ask people for links to the instructions they are following and then to compare their links against the “$300 Food Computer - MVP” post.

If nothing else, it would be fantastic if the main readme at https://github.com/futureag/mvp had prominent links to the most current build and software install instructions. The readme currently has some instructions, but they’re different from the google doc slide deck that seems to be the most authoritative software guide. The biggest challenge for me has been that it’s easy to find lots of links and guides, but I have to compare and cross-reference them to be sure I have the best one for the task at hand.


#4

Updated the prior post to correct the githug link.
The wiki is located at:


We need to get consistent (the problem of multiple sets of documentation), but at this time futureag is the ‘official’ software and documentation, though we don’t have the build information for the physical MVP (which is in the slides).


#5

@webbhm Oh, I see what you mean about the wiki now. Have you thought about moving those wiki files from the futureag/blog repository to the futureag/mvp repository so it’s more intuitive for people to find?

If you want to try it, migrating a github wiki from one repository to another is relatively simple (see documentation here). Based on testing in a couple of my own repositories, this procedure would probably get the job done:

git clone https://github.com/futureag/blog.wiki.git
# This clone will only work after you create & save a page in the MVP wiki
git clone https://github.com/futureag/mvp.wiki.git
cd mvp.wiki
cp ../blog.wiki/* .
git add .
git commit -m 'migrate wiki files'
git push

#6

We deliberately made it separate so when we have additional sensors and add-ons in different repositories, we don’t fragment the documentation.


#7

Okay. It sounds like you’ve already got a strategy then. I’ll leave you to it.


#8

As a user that did a recent install, one suggestion I would have is to move the info in the slide deck showing the software install to the github repo and put it in the README or a separate markdown file (still including screenshots and such).

This would not only be easier to read start to finish, but the community would be able to make pull requests to make suggestions to improve the documentation and fix any bugs or outdated info in the docs.

I’m happy to help with this if others agree its a good idea.

Also, the top level post here seems to still point to the old software repo $300 Food Computer - MVP


#9

Thanks for all the support and interest. I only apologize that things are so incomplete. That being said, this is an all volunteer (no funding) project right now. It’s hard to get people excited about documentation but I love that @vincitygialam and @jmitsch are taking an interest.

Please go ahead and put together a draft of what you’re proposing with regards to reformatting the documentation. I am especially interested in redoing the software, operational and FAQ’s.

@wsnook I agree that the documentation is confusing and I think an MVP ReadMe with updated links that could be made the one-stop shop for authoritative information on the MVP. We’ve gone through a lot of versions, I agree it’s a mess.

Here’s my question to all of you, if you had to edit down the $300 Food Computer - MVP thread links from the current 14, which ones would you eliminate? What is redundant/unecessary?


#10

tl;dr: I think most of those links are good, and they would easier to use if you organized them into a numbered outline or checklist that corresponds to the tasks people need to accomplish: shopping, building, software setup, and growing. You could omit the notes about revision dates.

Long version: As a starting point, rather than eliminating stuff or starting on a massive editing project, I would recommend picking one place–perhaps the readme on github, a wiki page, or whatever seems best–to organize the existing links with hardware and software documentation for the MVP. Then, once you have that, you could edit other places where those links are currently duplicated to just say something like, “for build, setup, and growing instructions, please refer to the documentation at [link to your official documentation place]”. Then, going forward, you would have one place to maintain rather than several. Maybe that’s what you meant by a “one-stop shop”–if so, that sounds good to me.

To take it a step further, you could organize the links into an outline (or checklist?) format with numbered sections. Your existing documentation is pretty good already, it’s just a bit challenging to navigate through it and talk about on the forum. As an example of something that’s working great, the slide numbers on your software installation slide deck are very helpful for conversations on the forum. Maybe you could extend the numbering concept to cover the whole procedure of shopping, hardware, software, and growing.

As for revising, reformatting, consolidating, etc. for the existing documentation after the old links are organized, I don’t have any strong opinions about it.


#11

The one thing I will add is I do think for a community-run open source project I do think it is important that the documentation can take contributions from the community. I’m not sure if google slides is the best for that, though I did find the slide organization and pictures helpful as is.

Moving things to a github repo would allow the community to make contributions to the documentation via pull requests. Markdown is powerful and you can use formatting, pictures screenshots, screengrab gifs, etc… You can even link directly to specific sections in it for easy reference it the forum. Also, the github UI makes it easy for the non-technical to open up a pull request. For these reasons, github would get my vote for a central place to host everything.

I agree with @wsnook that it would have to be something that is moved incrementally and perhaps just start with a collection of links to the current docs. Great idea!

One exception to that is I do think the software documentation should live with the software (obviously linked to from the appropriate places). If I get some free time I can open up a pull request to do just that so we can see how it looks and discuss further.

As far as the current docs, they really are good! I just had a few small hiccups where things are out of date or a little confusing, but other than that it was a good experience between the videos and slides :slight_smile: I just wish I could contribute back to them!

@Webb.Peter thanks for continuing the discussion


My experience building the MVP food computer