Documentation

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.

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, for instance agents enter, spend some time contributing and exit, and carry 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 having even more stuff getting 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 and capture more stuff from agents in that context. As more stuff gets deposited the organization as a place becomes valuable in the eyes of other agents, because whatever is deposited may have a use / importance for them. Thus, as stuff gets more deposited more agents are attracted towards the organization to contribute and create more stuff. Documentation is part of the 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 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 possibles 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.

Documentation can be construed as digital assets and requires discoverability (see transparency), accessibility (see openness), portability and interactivity.

The documentation process requires methods, norms (see governance) and tools.

Types of documentation

Following development processes

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]. 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. 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 indestructible, or a DIY documentation, containing instructions about how to fabricate one. In the context of use, a user manual is required, which contains instructions 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

1. 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,
2. who has designed it (may be the maker or someone in an open source hardware community, somewhere on the planet},

Open source designs come with an open source license, which usually imposes attribution, meaning that the documentation must contain information about the designer agent (individual or organization / network).

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.

Repositories

See more on the concept of repository.

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 tools 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.

Embedded documentation

Documentation embedded in the artifact. Proposed by Tibi in 2023. 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 device and provided with the device. Another alternative is to provide a link to a shared repository where the information lives.