Review of module 4: Open Hardware Specifics

[thessaly]

4.0 Intro to the module

• I'd remove this part and make the intro a single paragraph:

  As a basic example, when building a physical object, having a proper description of the materials used and why they were chosen makes it easier for everyone to use it, modify it or replicate it.

4.1 Accessible docs

• General description has old text

  Guidelines for documenting your hardware so most people can use it or contribute to it

• TOC: titles are too long, it's difficult to get at a gaze what the module is about. I suggest replacing by:

  Documenting for experts and newcomers Making it easier for the reader Identifying required skills Audiovisual formats in documentation Assignment Resources

• Make a new paragraph starting with "Just from this three examples"

• Rephrasing to make it more clear:

  A good approach to document things is to split it into to different documents each focused on one use case. This allows documenting to be more tractable and facilitates reading/watching. One suggestion would be to develop one document for using your hardware, one for building/assemblying it and one for developing it.

• When documenting a project it is normal to focus on the bits and pieces that go in the project it

Typos

• Just from thisese three examples

• How can I guide people to guide onebuild my hardware?

Assignment

• I'd move the "revisit your contribution guidelines and documentation plan" to a paragraph.

• Add the following:

  In previous modules you worked on your documentation plan. You can now work on adding content to that plan, check if it is useful or if it needs changes. Doesn't matter if you can't have a polished version right now, but add as much detail as possible to your documentation considering users (using and assemblying) and developers (contributing).

• Important, I think we may be confusing by using developer guides and contribution guidelines, I think we have to choose one and follow it, or define them very well in the glossary

Resources

They are OK, just need to be clickable

[vektorious]

4.0 Intro to the module

• I'd remove this part and make the intro a single paragraph:

  As a basic example, when building a physical object, having a proper description of the materials used and why they were chosen makes it easier for everyone to use it, modify it or replicate it.

Agree, makes it cleaner. Removed it.

4.1 Accessible docs

• General description has old text

  Guidelines for documenting your hardware so most people can use it or contribute to it

fixed

• TOC: titles are too long, it's difficult to get at a gaze what the module is about. I suggest replacing by:

  Documenting for experts and newcomers Making it easier for the reader Identifying required skills Audiovisual formats in documentation Assignment Resources

agree, fixed

• Make a new paragraph starting with "Just from this three examples"
• Rephrasing to make it more clear:

  A good approach to document things is to split it into to different documents each focused on one use case. This allows documenting to be more tractable and facilitates reading/watching. One suggestion would be to develop one document for using your hardware, one for building/assemblying it and one for developing it.

agree and fixed

• When documenting a project it is normal to focus on the bits and pieces that go in the project it

fixed

Typos

• Just from thisese three examples

• How can I guide people to guide onebuild my hardware?

fixed them

Assignment

• I'd move the "revisit your contribution guidelines and documentation plan" to a paragraph.

Did that and added "Improve your documentation" as title for the assignments

• Add the following:

  In previous modules you worked on your documentation plan. You can now work on adding content to that plan, check if it is useful or if it needs changes. Doesn't matter if you can't have a polished version right now, but add as much detail as possible to your documentation considering users (using and assemblying) and developers (contributing). fixed

• Important, I think we may be confusing by using developer guides and contribution guidelines, I think we have to choose one and follow it, or define them very well in the glossary

• I think we should discuss this. I'd actually rather stick to developer guides.

Resources

They are OK, just need to be clickable

made them clickable

[vektorious]

4. 2 Bill of Materials

Content

• replaced the summary: And how to make it useful for your contributors How to create a minimal viable documentation
• Removed "Content" heading in the beginning

Important: The first paragraph is describing "minimal viable documentation". It is kind of an introduction to BOMs, but I would suggest renaming the Submodule to "Minimal Viable Documentation". What do you think @amchagas @thessaly

• rewrote the start of the "Bill of Materials" Paragraph:

  The bill of materials, commonly just named "BOM" is usually in form of a table. It should contain information in a way that is makes it easy for interested people to know

• restructured the module: Bill of tools and Bill of skills are now a level higher (headline wise), I put "Access to materials in different parts of the world" after "Bill of Materials"
• Shorted the headline: Access to materials in different parts of the world

Assignments

• Changed title to: "Reach a minimal viable documentation"
• added this

  • Update your documentation with with:
    • Bill of materials
    • Bill of tools
    • Bill of skills

Resources

look good to me

[vektorious]

4.3 Digital fabrication & electronics

Content

Well, I wrote this submodule.. I realize (Seeing the other modules) it is a lot of text and talking around the topic. What do you think? @amchagas @thessaly

Assignments

• changed heading to "Improve your documentation"
• added the previous heading as bullet point:

  Revisit your documentation and take a look at the files formats you share, adjust if needed

Resources

• Removed "Guides" as heading and made it bold

Typos

wether -> whether

[vektorious]

4.4 User guides

Content

I wrote this module. It might contain some redundant information, but I think that's not necessarily bad.

Assignments

Added this as bullet points:

• If you do not yet have a bill of materials/tools/skills, write them
• Write building instructions/assembly guide/recipe
• Write something about how to use your hardware, try to include common pitfalls

Resources

There are none now. Should we add some best practice examples?

[vektorious]

4.5 Developer Guides

Content

Wrote it. It actually differentiates between contribution guidelines and documentation for developers. Developer guides is maybe both combined?

• Added a TOC, it was missing

Assignments

Added bullet points:

• Be sure to describe the current state of development of your project and point to open tasks

Ressources

I'd be great to add some good examples. Do we have one which we can use throughout the module?

[amchagas]

Resources (already added some to the units): 4.5 - a potential good example for guidelines: https://github.com/openUC2/UC2-GIT/blob/master/CONTRIBUTING.md 4.4 - from the same project as above, here is their guide for users https://github.com/openUC2/UC2-GIT/tree/master/TUTORIALS

[amchagas]

other than that, I like the updates!