review repository idea and items in it

[amchagas]

Hi!
Thinking about the next steps for this project, I thought it would be a good idea to have a repository template that contributors could use when they are developing tools, so that a certain uniformity is present, making it easier for people to go through different repositories and contribute.

This is a very initial sketch of this idea, and I would like as much input as possible at this point, including why this might be a terrible idea.

so please, when you have time, do take a look through and give me a piece of your mind! :)

Also let me know if the idea is not clear!

[vektorious]

Just to get it into my head: You are talking about something they could copy and fill it with their information to present/document their tool/product?

Just to get the discussion started. Why do you think this is needed?

[amchagas]

Yes, I'm thinking about a template people can easily "fill out" and have a "standardized" repository.

Take our own projects for instance:
https://github.com/amchagas/flypi/
and
https://github.com/vektorious/lightM

They are organised in different ways, although they could have the same structure. There are some printed parts, some electronics and some code, all of these could be organised in the same folder/file structure. Having both projects organised in the same way would:
a) make it easier for people to navigate both, even when they had only seen one of them before. (and here I'm thinking on users and reviewers/collaborators)
b) make it easier to see which parts could be used in other projects.

[vektorious]

Well, I agree with you! I think the biggest advantage might be that projects might get better documented ;)

But we have to agree on a structure. I actually like yours quite a lot. I'm not sure if it would make sense to have a code folder with all the Arduino etc things. We could try and polish our repositories and motivate others to do the same in order to list them as example repositories for OSH projects.

There are also a lot of resources from Mozilla Open Leaders on how to build a good project repository!

[amchagas]

There are also a lot of resources from Mozilla Open Leaders on how to build a good project repository!

cool, do you happen to have the links to those resources handy?

Also, could you add a bit why you think having a folder with all Arduino(and other microcontrollers/programmable) things wouldn't make sense?

[thessaly]

Hey, good idea. Also, @vektorious is right, from Mozilla Open Leaders there are many useful things.

Here is a presentation on READMEs I remixed from the program.

In general, if the project is open I'd ask for:

• One sentence explaining what the device does (similar to mission/vision in MozOL)
• LICENSE.md
• CONTRIBUTING.md

In particular for the case of hardware projects, my ideal repo would have:

• Bill of Materials with aprox cost, links to recommended suppliers' (this is one example)
• Fritzing diagram or equivalent for the electronics
• If the project involves some sort of sending data somewhere, I appreciate simple diagrams like this clarifying workflow
• Links to datasheets of components
• All the code in one place
• Current status of project: I think badges are super useful, like in this example, though I don't know if they exist for hardware. Would love to see some showing if there is someone from the team working on it or not, if the project works or there are failures... etc

It's a lot, but I said ideal :P

[emdupre]

This seems great -- I'm (almost) always pro templating ! 😺

I wonder if we couldn't work off of the structure that's been developed for standardizing small software projects, with tools like cookiecutter and shablona.

[vektorious]

Well I think I can't add more to what @thessaly wrote. Here is the link to the Mozilla program,

Well I think all code should be in one place and then separated for on which device it is going to run. Mainly a personal preference?

The two example tools for software are great and I think we can use a lot of their structure.

[thessaly]

Good idea @emdupre! We can contribute to cookiecutter with a template, it's a win-win. I didn't know about shablona, looks cool.

+1 @vektorious with that personal preference

[amchagas]

Thanks for the comments and links everyone!!

+1 for creating a template that could be added to Cookiecutter. Didn't know this existed to be honest. Thanks! @emdupre Which brings to the next question, has anyone worked with it and could take on the task of creating a package for it when we are done deciding what should be in the template? or induce me on how it works so I can do it?

@thessaly Some of your suggestions are already there (BOM and datasheets and all code in one place), I wonder if bringing them down to the "root" of the repo would help? Or even adding this tree structure in the readme.md like in Shablona? (Which I like quite a bit :) ) Having diagrams explaining where data comes from and where it goes is also a good idea!

@vektorious did you think about something like this?

[vektorious]

@amchagas I really like the tree structure because it clarifies the structure a lot but (IMHO) it is ugly as fuck...

Well maybe putting it in the end and set a link at the top would be a work around for that 😄

And yes, the structure the software folder has now is what I meant.

[jurra]

Hi Guys, maybe the template we have developed is already useful? We are extending a vuepress theme with other extra features for hardware and content presentation. It is a very extensible template, so maybe we could work there together and extended even more joining forces!

This is a demo example from one of our projects

I am making a demo also for @amchagas for the flypi. Soon I will be uploading it, also to get feedback!

[jurra]

I also started a demo for flypi this morning reusing the template:
https://go_commons.gitlab.io/fly-pi/

this is the repo where you can see the source code: https://gitlab.com/go_commons/fly-pi

[thessaly]

@thessaly Some of your suggestions are already there (BOM and datasheets and all code in one place), I wonder if bringing them down to the "root" of the repo would help? Or even adding this tree structure in the readme.md like in Shablona? (Which I like quite a bit :) )

I like the tree at the end like @vektorious said! I'd take them to root, but it's only my view =)

[vektorious]

@jurra that's a great idea! Might work with cookiecutter as well?

But then there are always two versions? The webpage repository and the actual project repository? Tbh combining both in one might get a bit confusing in regards to all the files that are required for the website to run.

[jurra]

@vektorious you could actually have it integrated in one repo, but then it will make things complicated. The way we are doing for other hardware is to separate web presentation from sources and repos. This allows us to solve several problems:

1. Separating documentation concerns from development concerns as separate git repos. This avoid problems with merging, collaborating etc.
2. If we have several repos that are part of a project, we can point to them using the website. So see the website as a higher level of content aggregation that is more userfriendly.

Remember that repos, in github have become more than repos, but also hubs for documentation with readmes. These new trend of templates and websites adds a layer with more documentation capabilities including videos, tutorials, and more.

About the cookiecutter, I would have to look more into it, but if we separate work repo from presentation repo, there shouldn't be a problem.

[vektorious]

Remember that repos, in github have become more than repos, but also hubs for documentation with readmes. These new trend of templates and websites adds a layer with more documentation capabilities including videos, tutorials, and more.

Absolutely but it adds a new complexity, too! For people who "just want to document their project" this might be a bit too much? Often people are already busy with getting their code uploaded and handle github/gitlab.

Don't get me wrong. I think your idea is great but maybe it's rather the next level of documentation for experienced hardware developer?

What we also tend to forget that there are already some .. well .. some kind of hardware repositories out there like hackster or hackaday. I mean this really does not work well with complex hardware project (in my opinion) but they have a great infrastructure (and you get awesome and arbitrary popularity points whith which you can compete against other projects!! 🎉)

To be serious. What is our target group?

[jurra]

@vektorious your reflection makes sense, but if you try the template and you see the example I am sure you will get that there is no complexity at all. On the other hand with this solution you can:

1. Keep working with git version control. Can you do this with wikifab? Probably not.
2. Be able to have the webdocumentation also locally and running the web appl locally on your computer.
3. Work offline on a git repo and seeing your changes locally without the need to make it public, which allows you to experiment and try different ideas of how you want to present your documentation.
4. Updating its just a push and a merge to the master branch (At least in gitlab, should be the same in github but I haven't tested).
5. You can develop new features for the template like image sliders, customized homepages, payment-donation solutions. This means that the solution its extensible and works mainly with javascript, and vuejs.
6. Vuepress supports internationalization. This is important if you want to have your website translated in different languages. I think spanish and chinese are very important languages to reach out more contributors and grow the community.
7. Responsiveness is very well implemented in this solution.

It is really an improvement compared to wikis, wordpress, and old static site content generators in general. Give it a try and you will see what I mean!

[vektorious]

Well, I'm using jekyll for my personal website and also for other projects but never tried Vuepress. But as far as I understood it's similar, that's why this was all about my personal experience jekyll but maybe I'm mistaken. And honestly, I felt overwhelmed at the beginning and that's why I brought up my concerns. But maybe my skills are just below the average. Anyways, I might give it a try soon because I have a project where a nice documentation is basically non existing.

[amchagas]

I'm super happy that this discussions are going on. Thanks! It is giving food for thought.

@jurra: I understand that you and the other peeps at Go Commons are thinking about these issues for a while and reiterating with the documentation system as well. It would be nice at some point to learn from your experiences and understand how did you got to this point! There is a constant discussion on the GOSH community about documentation and what is the best way to do it. This is not a trivial question...

At the same time I see @vektorious points. I also just recently learned about static websites and they are still a bit daunting for me (getting the file connections right, design, etc... Maybe I'm just slow for this :P )

So, one question/suggestion I have is the following:

If I understood correctly, the content of the landing page/documentation is stored in markdown files in the documentation repo.

This is in the end what the people creating the documentation want to work with and what they most likely will have the easier time to learn/start using, in case they never used it markdown and specially if they never used static websites.

So, would it be possible to have only these files as a subrepo inside the device repository, and as a part of the landing page/go commons system repo? something like this https://help.github.com/en/articles/splitting-a-subfolder-out-into-a-new-repository

This way I could see that people who have no skills with static websites, or that do not have time could in one go create their documentation in Markdown. Then at a later time, or through some automagically system, the go commons template could be used to pull this files and present them using the layout/vuepress system?

Maybe this was a bunch of non-sense, since I'm not sure I understand all the bits already.... IN that case, sorry! if not, would be happy to discuss further!

[thessaly]

@jurra those demos are awesome communication tools for projects!! I work a lot with people from other fields (that never used github, for example) and this is really, really useful.

On the other side, just my personal opinion, I like to find the raw md files easily in a repo (simple, quick, works everywhere), so I think it just depends on who is your target audience, as @vektorious says.

+1 to @amchagas idea, if there's a way to build with a click the website from these simpler docs, that would be an awesome addition (and necessary to scalate a project, IMHO).

[jurra]

Many thanks for the feedback 💟

Great discussion and reflection indeed!! This is great to reach an easy approach to this. @thessaly we should have both yes! That is what we have at the moment. Comprehensive web documentation and "source code documentation". Many of the readmes of the source documentation can be replicated, reused in the template.

@jurra: I understand that you and the other peeps at Go Commons are thinking about these issues for a while and reiterating with the documentation system as well. It would be nice at some point to learn from your experiences and understand how did you got to this point! There is a constant discussion on the GOSH community about documentation and what is the best way to do it. This is not a trivial question...

Yes that is right, we have worked and experienced different ways of working with wiki, github and gitlab. We found out that these approaches are limited in reaching out other potential collaborators, presenting the documentation in a comprehensive manner, and also have a format that is easy to maintain.

At the same time I see @vektorious points. I also just recently learned about static websites and they are still a bit daunting for me (getting the file connections right, design, etc... Maybe I'm just slow for this :P )

I think the best in this case is that you give it a shot in the repo I created, and you will find out how difficult it is or not. We have made the template so that by forking it, and configuring very small keys in values its ready. Believe me that learning git is way harder than this.

So, one question/suggestion I have is the following:
If I understood correctly, the content of the landing page/documentation is stored in markdown files in the documentation repo.This is in the end what the people creating the documentation want to work with and what they most likely will have the easier time to learn/start using, in case they never used it markdown and specially if they never used static websites.

Every piece of content you create in this template is in markdown. The only thing you need to do with regard to navigation is configuring the links and paths.

So, would it be possible to have only these files as a subrepo inside the device repository, and as a part of the landing page/go commons system repo? something like this https://help.github.com/en/articles/splitting-a-subfolder-out-into-a-new-repository

This is correct, it can be done, but it would be more tedious. For those who know how to handle git, shouldn't be a problem. We can try also this approach.

This way I could see that people who have no skills with static websites, or that do not have time could in one go create their documentation in Markdown. Then at a later time, or through some automagically system, the go commons template could be used to pull this files and present them using the layout/vuepress system?

About automation, the template is already quite automated, and also the deployment solution in gitlab is very automated. After cloning with two commands you can deploy the template locally (if you have nodejs installed).

To improve the template I think is good to have placeholders and demos that guide the user!!