Reviewed and made changes

[vektorious]

Do you agree with the content?

Yes

Do you agree with the opinions/statements

Yes

Any content to add/remove?

Home

• After reading the module I think we cover principles and tools but not values

  How to concretely build an open project? This week you will go through a set of principles values and tools >methods that will help you better organize your work and lower access barriers for users and contributors. You will then >apply them to start creating the building blocks of your open hardware project.

• Goal of the week

  Understand the design principles and methods that will allow you to facilitate collaborative work and apply them to >in your project

I agree and changed it.

3.1 "Version control"

• Use cases section: maybe we can add a sentence here to introduce the next section something link

  Although popular services such as Google Docs have version control and other useful features such as visual simultaneous collaboration, in open hardware we use version control in a different way. Added Nextcloud

• I'd incorporate the "history of GIT" section as paragraph 2 of "understanding GIT version control"

• I'd add the following to the "available platforms"section:

  What's the difference between git, GitHub, and GitLab? The three are often a source of confusion. Git, as we mentioned, is the software that handles version control, letting you make and track local file changes and share changes with a remote repository. GitLab, GitHub and others like BitBucket are platforms that offer services based on Git.

  GitHub is a cloud service for remote hosting of git repositories. In addition to hosting your code, the site helps manage software development projects with features like issue tracking, collaborating with other GitHub users, and hosting web pages. GitHub offers free services for open source projects (accessible to the public) and paid tiers for private projects. For public projects, anyone can see code you push to GitHub and offer suggestions, or even code, to improve your project. GitHub currently hosts the source code for tens of thousands of open source projects, but is not alone. BitBucket and GitLab.com offer comparable services.

  The most significant difference between the two is that while GitHub is a collaboration platform that helps review and manage codes remotely, GitLab is majorly focused on DevOps and CI/CD. GitHub is more popular amongst the developers as it holds millions of repositories, but recently GitLab has been gaining popularity, as the company continues to add new features to make it more competitive and user-friendly.

  Some institutions and sometimes people choose to run "self-hosted" instances of GitHub or GitLab. Self-hosting means you use your own resources (a server) to host and run applications instead of renting the services from the platforms. The benefit of self-hosting is that the user has complete control over their data, at a potentially lower monthly cost. The downside is that the user is responsible for maintaining the service. If the service encounters an error, the user is responsible for resolving the issue.

I agree and added your text. I also added BitBucket to the Platform list.

3.2 "Modularity"

• General description

  A way to facilitate organize your work, to facilitate reuse, contributions and repairability done

  • remove work in progress icon done
  • I think a basic definition of modularity is missing here, so everyone understands the same. We can add a para to the "Why is modularity useful section":

From Wikipedia: Modular design, or modularity in design, is a design principle that subdivides a system into smaller parts called modules which can be independently created, modified, replaced, or exchanged with other modules or between different systems. Modularity is used in open hardware projects because it makes it easier for others to take the parts that are useful to them and create derivatives, or contribute to specific features. Modularity is also really useful when a device breaks down, to easily detect and isolate a malfunction. Think of updates: if your design is modular, one module can become obsolete but you will be able to update it without changing the whole device.

Added it

• in "Reusability" title, the :rocket: emoji isn't rendering
• The 1st paragraph in the reusability section can benefit from ending after the question mark ("way?"). This can start another paragraph with the info already there, that continues like this:

In documentation this would mean highlighting the exact components in the system that are responsible for temperature sensing, and how it communicates with the rest of the system. In design/building, it would mean that the temperature sensing function is self-contained within a group of specific components, that can be replaced or modified easily.

Then the rest could make next paragraph longer:

In this way if another project wants to use just that function, it can easily find out what parts are needed and how it can be implemented somewhere else. Modularity is also useful within the project, as a certain module can be used more than one time in different parts of the system.

changed it accordingly

3.3 "A minimal viable product"

• General description:

  Minimum structure required for delivering performing a function done

• Delete WIP banner
• Typo: 1st paragraph,

  "end up spending a lot of time"

• Typo: 1st paragraph,

  "perfect before sharing it them with others"

• Typo, bullets in "the concept of prototypes" section:

  "finding out quickly" "getting a sense of project evolution," "contribute to the project as things its functions" corrected all,

3.4 "Documenting for whom"

• erase WIP banner

• General comment, TOC titles should be shorter

  "Documentation needs to be easy to use/modify (using mature OS tools and text formats contributes to that)" Don't format resources with title headers, because they appear in the TOC

• 1st para reads too long, can be changed for:

  Documenting your project is a crucial step and really makes the difference on whether a project is only going to be usable by its creators, or by a wider community. In open projects, where creators/developers are encouraged to share their work early and often, documentation should be considered a “living”, often changing part of the project.

  Waiting for the project to be done before starting documentation increases the chances that documentation stays on the “back burner” for too long, preventing others from contributing/using your work. Therefore, it is a good idea to already start thinking about how, what and in which system you are going to document your project. Additionally (see below), you should also think about who is your audience and what kind of information they need to be able to join as users and/or developers.

Hm. Maybe the bullet points are somewhat redundant, but I'm not sure if we really need to shorten the first paragraph so much. Or are you talking about just the very first paragraph from "Documenting .. " to "... your work." ?

Any more resources?

For 3.1

• GitHub vs GitLab: Difference Between GitHub and GitLab Added

For 3.2

• https://wiki.p2pfoundation.net/Modularity_in_Open_Source Added

For 3.3

For 3.4

Are the assignments appropriate

For 3.1

Yes, I'd add here a sentence introducing how we use version control in hardware projects. Something like:

VCS are really useful for handling your hardware project files. If you use a platform like GitLab or GitHub, you have the advantage of using VCS and making your repository publicly available. Think of the files that you need to track along the life of your project.

• Which are these files?
• Which platform suits your needs better?
• How do you plan to organize your repository so people can quickly find your project files?

I agree and added that.

For 3.2

Assignment missing description, add: The following questions can guide your way towards modular design:

• Which are the main functions required for your hardware to operate?
• Based on that, how many would modules you need to create and how would they group the components of your project? E.g., power module, microcontroller, communication, temperature sensor
• How would you interconnect those modules? How much space will your modules take once interconnected? (Think of enclosures!) Added

For 3.3

I'd move the title of the assignment below as text. I'd also add the following:

To do this, go back to your project vision and review your project goal. Now think back: which minimum functions are needed to achieve that goal? Did that, changed the heading to "Project Review"

For 3.4

Typos/re-phrase

For 3.1

Think about the times you worked in collaboration with someone, where you were both writing in the same wWord document.

the same part of the text the other person was working on

On top of that you had to create multiple versions of the file there were many versions of the file being created, so that you could keep track of the most recent version changes.

Changed it to:

On top of that you had to create multiple versions of the file, so that you could keep track of the most recent changes.

• unefficient > inefficient
• Luckly > Luckily
• overwritting > overwriting

uUse cases and examples

• Change for mentees or participants

  For OHM we suggest users to take a look and understand the basics of GIT so that they can use it on their project workflow.

• Make it more personal

  Initially users you should understand three main GIT commands:

• Command format

• git add

• git commit

• git push

• mMore details about git and getting started can be found in the resources section.

Corrected them.

For 3.2

• Examples and use cases:

  Thisese little boards corrected

For 3.3

For 3.4

In the Assignements

• regurlarly -> regularly

[amchagas]

looks good to me! Thanks both!