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
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
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
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?
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?
4.0 Intro to the module
Agree, makes it cleaner. Removed it.
4.1 Accessible docs
fixed
agree, fixed
agree and fixed
fixed
Typos
fixed them
Assignment
Did that and added "Improve your documentation" as title for the assignments
Resources
made them clickable
4. 2 Bill of Materials
Content
And how to make it useful for your contributorsHow to create a minimal viable documentationImportant: 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
in different parts of the worldAssignments
Resources
look good to me
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
Resources
Typos
wether -> whether
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:
Resources
There are none now. Should we add some best practice examples?
4.5 Developer Guides
Content
Wrote it. It actually differentiates between contribution guidelines and documentation for developers. Developer guides is maybe both combined?
Assignments
Added bullet points:
Ressources
I'd be great to add some good examples. Do we have one which we can use throughout the module?