Documentation - Revision history

TiberiusB at 21:51, 5 October 2026

2026-10-05T21:51:31Z

TiberiusB: /* Praxix */

2024-01-04T00:07:18Z

Praxix

TiberiusB: /* Embedded documentation */

2024-01-04T00:07:04Z

Embedded documentation

TiberiusB: /* Embedded documentation */

2024-01-04T00:04:15Z

Embedded documentation

TiberiusB: /* Types of documentation */

2024-01-04T00:00:08Z

Types of documentation

TiberiusB at 23:59, 3 January 2024

2024-01-03T23:59:38Z

TiberiusB: /* Types of documentation */

2024-01-03T23:58:55Z

Types of documentation

TiberiusB: /* Relevancy */

2024-01-03T23:50:23Z

Relevancy

TiberiusB: /* Repositories */

2024-01-03T23:49:04Z

Repositories

TiberiusB: /* Types of documentation */

2024-01-03T23:41:06Z

Types of documentation

@@ Line 1: / Line 1: @@
 Content produced to pass on data, information, knowledge and [[know how]] about a [[process]] or a thing.
-This activity may require [[harvesting]] a [[capturing mechanism]], a support (digital of physical), formatting (or structuring), storage (ex. database, see also [[repository]]) with an associated (file) format.
+This activity may require [[harvesting]], a [[capturing mechanism]], a support (digital of physical), formatting (or structuring), storage (ex. database, see also [[repository]]) with an associated (file) structure.
-Documentation can also be seen as an [[accumulation mechanism]], and is considered as a form of wealth. For example, a context of work, a [[project]], a [[venture]], a network, can be seen as a flow-through [[organization]], i.e. [[agents]] enter, spend some time contributing and exit, carrying with them [[resources]]. We can use the metaphor of a river, carrying various materials. In some places the river flows rapidly and nothing much gets deposited locally. In other places, the river slows down and stuff can be deposited. As vegetation starts growing, it acts as as a barrier or a filter for some materials, consisting a [[capturing mechanism]], slowing the river even more and causing even more stuff to be deposited locally. Ecosystems are formed around these areas, with an increase in diversity. This metaphor can be applied to an [[organization]], which is a local context through which [[agents]] flow and carry with them [[resources]] and engage in generative [[processes]], creating new stuff. The [[organization]] must put mechanisms in pace to slow down the flow of agents and capture stuff from them and deposit it in that local context. As more stuff gets deposited the organization becomes [[valuable]] in the eyes of other [[agents]], because whatever is deposited may have a use / importance for them. Thus, as more stuff gets deposited more [[agents]] are attracted towards the [[organization]] to contribute and create more stuff. Documentation is stuff that gets deposited. Imposing documentation through [[governance]], incentivizing documentation by offering various types of rewards / [[benefits]], facilitating documentation by providing tools (ex. Google Docs) are all measures that must be taken to increase the [[wealth]] of an [[organization]], to make it more valuable.
+Documentation can also be seen as an [[accumulation mechanism]], and is considered as a form of shared wealth that the network accrues. For example, a context of work (i.e.a [[project]], a [[venture]], a network) can be seen as a flow-through [[organization]], i.e. [[agents]] enter, spend some time contributing and exit, carrying with them [[resources]]. We can use the metaphor of a river, carrying various materials. In some places the river flows rapidly and nothing much gets deposited locally. In other places, the river slows down and stuff can be deposited by sedimentation. As sediments grow, vegetation starts growing and acting as as a barrier or a filter for other materials, consisting a [[capturing mechanism]], slowing the river even more and causing even more stuff to be deposited locally. Ecosystems are formed around these areas, with an increase in diversity. This metaphor can be applied to an [[organization]], which is a local context through which [[agents]] flow and carry with them [[resources]] and engage in generative [[processes]], creating new stuff. The [[organization]] must put mechanisms in pace to slow down the flow of agents and capture stuff from them and deposit it that in the local context. As more stuff gets deposited, the organization becomes [[valuable]] in the eyes of other [[agents]], because whatever is deposited may have a use / importance for them. Thus, as more stuff gets deposited more [[agents]] are attracted towards the [[organization]] to contribute and create more stuff. Documentation is stuff that gets deposited. Imposing documentation through [[governance]], incentivizing documentation by offering various types of rewards / [[benefits]], facilitating documentation by providing tools (ex. Google Docs) are all measures that must be taken to increase the [[wealth]] of an [[organization]], to make it more valuable.
-Documentation is also related to the concept of [[adjacent possible]], which is a thing that can be created by combining already existing things and perhaps adding a new ingredient to it. In the [[open source]] world this is also called [[remixing]]. The wealth of [[adjacent possible]]s is related to innovation capacity. This is one of the economic advantages of open networks that relay on open collaboration and [[open innovation]] (open source development)
+Documentation is also related to the concept of [[adjacent possible]], which is a thing that can be created by combining already existing things and perhaps adding a new ingredient to it. In the [[open source]] world this is also called [[remixing]]. The wealth of [[adjacent possible]]s is related to ''innovation capacity''. This is one of the economic advantages of ''open networks'' that relay on ''open collaboration'' and [[open innovation]] (open source development), when compared with traditional firms or other of traditional and bureaucratic institutions. See also about the [[4th Sector]].
@@ Line 19: / Line 18: @@
-When it comes to applied knowledge, we are in the [[design]] and [[prototyping]] area of activity, and the proper documentation is an [[R&D doc]], which contains information about why things are the way they are, what has been tested, what has worked and failed, etc. At this level other
+When it comes to applied knowledge, we are in the [[design]] and [[prototyping]] area of activity, and the proper documentation is an [[R&D doc]], which contains information about why things are the way they are, what has been tested, what has worked and failed, etc. At this level, other digital artifacts can be produced, which are very formal representation of a physical object, in the form of 3D CAD files or schematics of a PCB, of blueprints of a furniture or building, software, etc. These purely technical and formal documents often require more sopfisticated tools for their creation, maintenance and collaboration, such as git (for software), [https://3dwarehouse.sketchup.com/ 3D wearhouse] for 3D models, etc.
-[[File:Documentation acording to process.jpg|thumb]]
+[[File:Documentation according to process.jpg|thumb]]
-When a [[design]] reaches maturity it can be fabricated by agents that have not taken part in the design process.
+When a [[design]] reaches maturity it can be fabricated by [[agents]] that have not taken part in the design process.
 In the fabrication domain of activity the proper documentation is an [[instructible]], or a [[DIY documentation]], containing instructions about how to fabricate one. These other formal representations will also accompany the instructible.
 In the context of use, a [[user manual]] is required, which contains about safe use of the artifact, troubleshooting, repair / upgrade and end of life.
-When a production process goes through all the stages mentioned above, proper [[material peer production]] requires all these types of documentation to be produced. It is also required that these documents interlink (allowing one to navigate from one to another), and provide a path to the context in which the work has been performed. For example, the user manual needs to provide, at minimum, information about
+When a production process goes through all the stages mentioned above, proper [[material peer production]] requires all these types of documentation to be produced. It is also required that these documents interlink (allowing one to navigate from one to another), and provide a path to the context in which the work has been performed. For example, the ''user manual'' needs to provide, at minimum, information about
 # who has fabricated the artifact (it may be the user itself, in which case a user manual is not required), perhaps someone in a [[makerspace]],
 # who has designed it (may be the maker or someone in an open source hardware community, somewhere on the planet},
@@ Line 36: / Line 34: @@
 It is also highly recommendable to include information about how to interact with other agents that have engaged with the design or the artifact, as designers, fabricators or users, where one can ask questions, learn more, exchange experiences, provide feedback, etc. Usually this takes the form of a link to a discussion forum or to a wiki.
@@ Line 48: / Line 48: @@
 =Relevancy=
-In a highly collaborative environment documents are live, open to participation to various degrees, but certainly transparent (public read access). Documents are considered alive if they are still relevant in terms of collaboration. As such, they are subject to change, based on their future use.
+In a highly collaborative environment documents are ''alive'', open to participation to various degrees, but certainly transparent (public read access). Documents are considered alive if they are still relevant in terms of collaboration. As such, they are subject to change, based on their future use.
 Some documents are frozen, they only have a historical value. Freezing a document becomes necessary when its historical value becomes more important, to provide a snapshot in time in the evolution process of something.
@@ Line 56: / Line 56: @@
-PRAXIS: [[Sensorica]] has historically used Google docs for live documents and PDFs, saved in Google drives with the live docs, for archived documents. The PDF format is considered more stable and highly portable, thus more suitable for long-term storage with a good probability of future accessibility. Archived documents have the term ARCHIVE in their name, to make them easily identifiable and searchable.
+PRAXIS: [[Sensorica]] has historically used Google Drive to produce and store documentation. The PDF format is considered more stable and highly portable, thus more suitable for long-term storage with a good probability of future accessibility. Archived documents are saved in PDF and have the term ARCHIVE in their name, to make them easily identifiable and searchable.
 =Repositories=
@@ Line 63: / Line 63: @@
 Documentation takes the form of a [[digital asset]] and usually lives as a file in a database. Some documents live on platforms, specialized repositories, where some other data can be aggregated related to their creation, use, fork, remix, etc. These platforms also offer functionality for process management, history and versioning, various collaboration tools, including discussion forums. Good examples are Github and Gitlab. In essence these platforms are designed to become attractors, i.e. incentivize agents to deposit their documentation within them, making them even more attractable. The problem is that these platforms, although they offer many possibilities of remix and allow emergence to happen from the aggregated content, they do become silos, impose their will on the community of developers and extract value unilaterally from the aggregated data.
-Documentation can be seen as [[digital assets]] and live as true [[commons]] on distributed storage systems, accessible by anyone at any time. They can live not as files, but as dapps, providing all the capabilities that Github provides, for example, even navigation to other related digital assets.
+Documentation can be seen as [[digital assets]] and live as true [[commons]] on distributed storage systems, accessible by anyone at any time. They can live not as files, but as dapps, providing all the capabilities that Github provides, for example, even navigation to other related digital assets. See more on [[NDO]].
 =Standards=
-Documentation needs to follow standards for various reasons. First, in the digital age it must be machine readable, searchable and retrievable. Also, the documentation needs to be easily actionable. It must be presented in a format that allows rapid understanding, clarity, precision. Since peer production is a distributed process, agents need to compare and remix designs, for example, and a documentation standard allows agents to easily compare.
+Documentation needs to follow standards for various reasons. First, in the digital age it must be machine readable, searchable and retrievable. Also, the documentation needs to be easily actionable. It must be presented in a format that allows rapid understanding, clarity, precision. Since [[peer production]] is a distributed process, [[agents]] need to compare and remix designs, for example, and a documentation standard allows agents to easily compare.
 The Internet of Production Alliance (IoPA) is engaging actors in material peer production to design and adopt documentation standards, see more on [https://www.internetofproduction.org/openknowhow OKH, or open know how].

@@ Line 75: / Line 75: @@
 =Praxix=
-See [https://docs.google.com/document/d/1pB901EfuFigFjmbWEg9VF7zwr4w9mv4ayXsl9FLC1y8/edit?hl=en_US Sensorica's document on documentation
+See [https://docs.google.com/document/d/1pB901EfuFigFjmbWEg9VF7zwr4w9mv4ayXsl9FLC1y8/edit?hl=en_US Sensorica's document on documentation]
 [[Category:Documentation]]  [[Category:Digital Assets]]

← Older revision		Revision as of 00:07, 4 January 2024
Line 74:		Line 74:
	Documentation embedded in the artifact. If we think about software, documentation can be written in the code as comments. If we think about hardware devices, the documentation can be stored in some type of device. If it is an electronic device, it can be stored in the memory of the device, assuming that the device is provided with memory. This info could be accessed via some type of wired or wireless communication protocol. An example would be to scan a QR code to connect to the device for a file transfer and reading that file on a mobile device. If this is only a mechanical device, the information can be stored in some type of flash memory and provided with the device. Another alternative is to provide a link to a shared repository where the information lives.		Documentation embedded in the artifact. If we think about software, documentation can be written in the code as comments. If we think about hardware devices, the documentation can be stored in some type of device. If it is an electronic device, it can be stored in the memory of the device, assuming that the device is provided with memory. This info could be accessed via some type of wired or wireless communication protocol. An example would be to scan a QR code to connect to the device for a file transfer and reading that file on a mobile device. If this is only a mechanical device, the information can be stored in some type of flash memory and provided with the device. Another alternative is to provide a link to a shared repository where the information lives.

		+	=Praxix=
		+	See [https://docs.google.com/document/d/1pB901EfuFigFjmbWEg9VF7zwr4w9mv4ayXsl9FLC1y8/edit?hl=en_US Sensorica's document on documentation

	[[Category:Documentation]] [[Category:Digital Assets]]		[[Category:Documentation]] [[Category:Digital Assets]]

← Older revision		Revision as of 00:04, 4 January 2024
Line 75:		Line 75:


−	[[Category:Documentation]]	+	[[Category:Documentation]] [[Category:Digital Assets]]

@@ Line 21: / Line 21: @@
 When it comes to applied knowledge, we are in the [[design]] and [[prototyping]] area of activity, and the proper documentation is an [[R&D doc]], which contains information about why things are the way they are, what has been tested, what has worked and failed, etc. At this level other
 digital artifacts can be produced, which are very formal representation of a physical object, in the form of 3D cad files or schematics of a PCB, of blueprints of a furniture or building.
 When a [[design]] reaches maturity it can be fabricated by agents that have not taken part in the design process.
@@ Line 34: / Line 36: @@
 It is also highly recommendable to include information about how to interact with other agents that have engaged with the design or the artifact, as designers, fabricators or users, where one can ask questions, learn more, exchange experiences, provide feedback, etc. Usually this takes the form of a link to a discussion forum or to a wiki.

← Older revision		Revision as of 23:59, 3 January 2024
Line 35:		Line 35:
	It is also highly recommendable to include information about how to interact with other agents that have engaged with the design or the artifact, as designers, fabricators or users, where one can ask questions, learn more, exchange experiences, provide feedback, etc. Usually this takes the form of a link to a discussion forum or to a wiki.		It is also highly recommendable to include information about how to interact with other agents that have engaged with the design or the artifact, as designers, fabricators or users, where one can ask questions, learn more, exchange experiences, provide feedback, etc. Usually this takes the form of a link to a discussion forum or to a wiki.

−	[[File:Documentation ~~according~~ to process.jpg\|thumb]]	+	[[File:Documentation acording to process.jpg\|thumb]]

← Older revision		Revision as of 23:50, 3 January 2024
Line 47:		Line 47:


−	PRAXIS: [[Sensorica]] has historically used Google docs for live documents and PDFs, saved in Google drives with the live docs, for archived documents. The PDF format is considered more stable and highly portable, thus more suitable for long-term storage with a good probability of future accessibility.	+	PRAXIS: [[Sensorica]] has historically used Google docs for live documents and PDFs, saved in Google drives with the live docs, for archived documents. The PDF format is considered more stable and highly portable, thus more suitable for long-term storage with a good probability of future accessibility. Archived documents have the term ARCHIVE in their name, to make them easily identifiable and searchable.

	=Repositories=		=Repositories=

← Older revision		Revision as of 23:49, 3 January 2024
Line 36:		Line 36:

	[[File:Documentation acording to process.jpg\|thumb]]		[[File:Documentation acording to process.jpg\|thumb]]
		+
		+	=Relevancy=
		+
		+	In a highly collaborative environment documents are live, open to participation to various degrees, but certainly transparent (public read access). Documents are considered alive if they are still relevant in terms of collaboration. As such, they are subject to change, based on their future use.
		+
		+	Some documents are frozen, they only have a historical value. Freezing a document becomes necessary when its historical value becomes more important, to provide a snapshot in time in the evolution process of something.
		+
		+
		+	Note that live documents can also provide access to history, i.e. snapshots in time as they were modified by contributors.
		+
		+
		+	PRAXIS: [[Sensorica]] has historically used Google docs for live documents and PDFs, saved in Google drives with the live docs, for archived documents. The PDF format is considered more stable and highly portable, thus more suitable for long-term storage with a good probability of future accessibility.

	=Repositories=		=Repositories=

← Older revision		Revision as of 23:41, 3 January 2024
Line 16:		Line 16:
	=Types of documentation=		=Types of documentation=

−	Documentation is process specific. For example, at the philosophical or scientific level we find scientific publications and books. See also [[Tibi]]'s idea of [~~scientific oeuvrehttps~~://sites.google.com/view/tiberiusbrastaviceanu/philosophy/the-scientific-oeuvre\|scientific oeuvre].	+	Documentation is process specific. For example, at the philosophical or scientific level we find scientific publications and books. See also [[Tibi]]'s idea of [https://sites.google.com/view/tiberiusbrastaviceanu/philosophy/the-scientific-oeuvre scientific oeuvre].