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, 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 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
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 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. 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. 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
- 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},
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.
PRAXIS
Sensorica has name tags to signify important types of documents. For example:
- (S)--name-- signifies a document describing important organizational matters, such as governance.
- ARCHIVE--name-- signifies a frozen document, usually in PDF format, for historical purposes.
- TEMPLATE--name-- signifies a document that contains a methodology of work, intended to make processes uniform across projects or ventures
Sometimes these name tags are composed in the name of a doc.
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. Archived documents have the term ARCHIVE in their name, to make them easily identifiable and searchable.
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 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.
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.
The Internet of Production Alliance (IoPA) is engaging actors in material peer production to design and adopt documentation standards, see more on OKH, or open know how.
Embedded documentation
- Proposed by Tibi in 2023.
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.