diff --git a/README.md b/README.md new file mode 100644 index 0000000000000000000000000000000000000000..de7e0da7fa8890ed9719b27d2bb1c4d0c0937554 --- /dev/null +++ b/README.md @@ -0,0 +1,62 @@ +# Convergence of BuildUp and DocuBricks + +## Structure +### DocuBricks +[Docubricks]{https://docubricks.com/} is a documentation platform, where the files are written wit an offline editor. The DocuBricks documentation is stored in a single XML file which contains 3 types of top-level elements: + +* Authors - Exactly as expected +* Parts - This is a simple part that bought or made +* Bricks - These are more complex assemblies built out of parts or other bricks. They have assigned authors and step-by-step assembly instructions. + +### BuildUp + +BuildUp is the format used by the software [GitBuilding]{https://gitbuilding.io}. BuildUp documentation is stored in a directory. The documentation contains 3 types of files (plus any images/CAD drawings/etc): + +* A Configuration file - This is a YAML file that defines things like the authors. It can also be used to customise the exported documentation +* Part libraries - These are YAML files that define simple parts that can be bought/made +* BuildUp Pages - These are pages are in "BuildUp markdown" this is a modified markdown with extra meta data. A page can contain any information that is seen as necessary. The page be used to describe a part that is hard to explain using a part library, it can describe a process, a step in the instructions, or any other information. + +## Similarities and differences + +While the XML data schema for DocuBricks Authors and Parts are slightly different to the YAML schema used in BuildUp this could easily be aligned. It is worth noting that authors are global for BuildUp but can be defined on a per Brick basis in DocuBricks, giving DocuBricks more fine grained authorship data. + +Both formats are designed to be hierarchical with the key hierarchical elements in the hierarchy being Bricks for DocuBricks, and BuildUp pages for BuildUp + +There are key differences between Bricks and BuildUp pages. Bricks have describe a assembled hardware part, it has elements such as assembly steps, or required components, these components can be bricks, this is how the hierarchy is defined. BuildUp pages are free-form and can be used to describe anything from extra information, to processes, to steps in an instruction. The hierarchy is defined by metadata in hyperlinks between pages. + +## BuildUp documentation structure in detail + +A BuildUp is an extension of markdown. Markdown is commonly used for writing generic static websites using site generators such as [Jekyll](https://jekyllrb.com/) or [MKDocs](https://www.mkdocs.org/). BuildUp then adds extra metadata links to allow part and tool usage to be automatically counted, and to define the page hierarchy. By never defining any BuildUp metadata in the pages, BuildUp can still be used to make a simple generic website. This freedom means that if a project has unique needs it should be able to manually document them. + +### Link types + +Metadata can be added to hyperlinks to: +* Define another step that must be completed - these define the hierarchy +* To define a part that needs to be counted +* An "output", something made on this page + +An graphical example (some syntax is omitted for brevity) is: + +![](diagrams/Steps.png) + +### Automatic Bill of Materials + +A key benefit of this is that you don't need explicitly define your bill of materials, you just need to indicate when a part is used. When that instruction is modified so is the bill of materials. Parts can be divided into different categories. By default the categories are "Parts" and "Tools", where parts are counted but tools are re-used (custom parts can be defined in the configuration). As shown in the following screenshot: + +![](diagrams/Categories.png) + +### Complex and forked hierarchies + +By using the links to define which pages are a part and which is a step can allow a project to treat another piece of open hardware as a simple component, while still including the instructions to build this part. It also handles complex situations such as self-replicating hardware like the RepRap when the part being made is also a required part. + +![](diagrams/Recursive.png) + +The structure should handle variations on a similar design. Many of the same input pages can be used, but separate versions of these pages will be created that refer to the correct steps and outputs. + +![](diagrams/Variations.png) + +In practice some of the syntax described above cannot be processed until [v0.7](https://gitlab.com/groups/gitbuilding/-/milestones/3) of GitBuilding is released (hopefully in August). + +### Extensible: Future direction + +Adding extra link types adds complexity but provides a way to define extra metadata directly in the text. We have plans to define links for quality control/assurance procedures, so that procedures can be reused and so that assembly checklists can automatically be generated. diff --git a/diagrams/Categories.png b/diagrams/Categories.png new file mode 100644 index 0000000000000000000000000000000000000000..4546c9d489618a611141ecf4a50a18fd779021c7 Binary files /dev/null and b/diagrams/Categories.png differ diff --git a/diagrams/Recursive.png b/diagrams/Recursive.png new file mode 100644 index 0000000000000000000000000000000000000000..fca93fa5dcc61e59095e7c90aaf1a40fc75445c4 Binary files /dev/null and b/diagrams/Recursive.png differ diff --git a/diagrams/Recursive.svg b/diagrams/Recursive.svg new file mode 100644 index 0000000000000000000000000000000000000000..4e780653ede6b001d89168e2836218c32fe93076 --- /dev/null +++ b/diagrams/Recursive.svg @@ -0,0 +1,930 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + Bill of materials:1 x RepRap200g of PLASome other parts + + + Bill of materials:Lots of plastic partsSome other parts + Bill of materials:1 x RepRap200g of PLA + + # Other partsAll the other things! + + + + + Step link: Full bill of materials of linked page is counted + + + + Part link: Only linked item is counted in bill of materials. + + + # PLAFillament for printing + # Printing partsFrom the design filesprint the parts from[PLA]{Qty: 200g} Usinga [RepRep]{Qty: 1}.You now have some[platic parts]{output,Qty: Lots} + # AssembleAssemble the [plasticparts]{Qty: Lots}with [other parts]{Qty: some}. + + + Output link: A part linkto something defined inanother step. + + + # RepRap PrinterYou can [buy a RepRap]but you can also makeone! To make one youneed to* [Print parts]{step}* [Assemble]{step} + + + # Buy a RepRapThis could give lots ofoptions of different placesto buy RepRaps. + + + + + Standard Hyperlink + + + diff --git a/diagrams/Steps.png b/diagrams/Steps.png new file mode 100644 index 0000000000000000000000000000000000000000..ad373d708baa92086b0790748f2dc9d6557d59a9 Binary files /dev/null and b/diagrams/Steps.png differ diff --git a/diagrams/Steps.svg b/diagrams/Steps.svg new file mode 100644 index 0000000000000000000000000000000000000000..f42cda56c67aa36072d1103560569644f9889d89 --- /dev/null +++ b/diagrams/Steps.svg @@ -0,0 +1,1052 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + Bill of materials:1 x saw6 x planks of wood100 ml of glue25 x wood screws + + + Bill of materials:12 x bits of wood100 ml of glue25 x wood screws + Bill of materials:1 x saw6 x planks of wood + + # GlueWood glue, not super glue + + # Wood screwsUse 3.5 x 25mm wood screws. Remeber to drill a pilot hole with a [2mm drill bit]{Qty: 1} + + + + + Bill of materials:1 x 2mm drill bit + + + Step link: Full bill of materials of linked page is counted + + + + Part link: Only linked item is counted in bill of materials. + + + # Plank of woodFlat, planed planks of wood. Oak is best. + + # SawA wood saw. + # Cut woodUse a [saw]{Qty: 1} to cut six [planksof wood]{Qty: 6}.You now have 12 [bitsof wood]{output,Qty:12} + # AssembleAsseble the [bits ofwood]{Qty: 12} with[glue]{Qty: 100 ml}and [wood screws]{Qty: 25} + + + Output link: A part linkto something defined inanother step. + + + # Making a chairTo make the chair you should:* [Cut wood]{step}* [Assemble]{step} + diff --git a/diagrams/Variations.png b/diagrams/Variations.png new file mode 100644 index 0000000000000000000000000000000000000000..f35ec01becb2e9e52b7098af86a53623f76398b7 Binary files /dev/null and b/diagrams/Variations.png differ diff --git a/diagrams/Variations.svg b/diagrams/Variations.svg new file mode 100644 index 0000000000000000000000000000000000000000..92b4c5c0402d28bcf9f63a51db977328ad1f26f8 --- /dev/null +++ b/diagrams/Variations.svg @@ -0,0 +1,1395 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + image/svg+xml + + + + + + + + + + Step link: Full bill of materials of linked page is counted + + + + Part link: Only linked item is counted in bill of materials. + + + + Output link: A part linkto something defined inanother step. + + + + + Standard Hyperlink + + + + + + + + + + + + + Bill of materials:1 x RepRap200g of PLA1 x expensive lens1 x microscope objective18 x screws + + # Fancy MicroscopeTo make the fancymicroscope youshould* [Print the parts]{step}* [Assemble fancyoptics]{step}* [Final assembly]{step} + # Open MicroscopeThis open microscopehas two variations:[fancy] and [simple]. + # Simple MicroscopeTo make the simplemicroscope youshould* [Print the parts]{step}* [Assemble simpleoptics]{step}* [Final assembly]{step} + # Printing partsFrom the design filesprint the parts from[PLA]{Qty: 200g} Usinga [RepRep]{Qty: 1}.You now have some[platic parts]{output,Qty: Lots} + + # Fancy opticsAssemble an [expensivelens]{Qty: 1} and a[microscope objective]{Qty: 1}.You now have an[optics module]{output, Qty: 1} + + # Simple opticsAssemble a [cheaplens]{Qty: 1} and a[small tube]{Qty: 1}.You now have an[optics module]{output, Qty: 1} + # Final assemblyAssemble the [plasticparts]{Qty: Lots}with some [screws]{Qty: 18}. Finally,clip in the [opticsmodule{Qty: 1}. + Bill of materials:1 x RepRap200g of PLA1 x cheap lens1 x small tube18 x screws + + + + Note: Two different versionsof this page are in the ouput.In one [optics module] toFancy optics, the other toSimple optics + + + + + + +