2018-07-20

PM1 - Pro Memoria - For Memory

The written word is a powerful tool for knowledge transfer to colleagues and future self. Still, documentation is often neglected in favor of more tangible things like new products and features. One culprit could be an overly complicated process for writing and maintaining documents. Revising large documents and coordinate contributions from many authors can be daunting.The goal of the PM system described here is to simplify the task to share product designs, processes, utility guides, tool descriptions and ways of working within an organisation.

A PM is typically fairly short, like a blog post. It should be possible for one person to write a PM in a day or a few hours. Multiple PMs are required to describe all aspects of a large system.

A PM is assigned an unique identity, e.g. PM1, PM2, PM3 and so on.

A PM can be revised if it contains errors or needs to be improved. The first revision of PM27 is called PM27.1, the second is called PM27.2 and so on. (See also Properties of Version Numbers).

If the thing being described has changed then a new PM should be written. Old things will come back to haunt you and then it is good to have the documentation readily available. The underlying philosophy here is that a PM should be a stable value that doesn't change with the times. Let's assume you have described the build process for you product in a PM. Release 5 of the product has a new build system. You should keep the original PM and clarify that it covers product releases 1 to 4 and write a new PM for product release 5. (See also The Value of Values). The information that is allowed to continuously grow in a PM is the set of relations it has to other PMs.

A Wiki could be a suitable tool for your PMs.

If you need to organize related PMs in a larger structure, then do that in a PM. You are allowed to append to such a structural PM, but preferably not replace referenced PMs with superceeding ones. If this becomes necessary, then create a new structural PM to maintain the history intact. Don't start out by creating a lot of structural PMs with no content. Let the structure grow organically when you have PMs with actual content to organize.

For practical purposes it may also be necessary to keep a volatile list of the most up to date PMs in a well known location, e.g. the front page of a Wiki.

An alternative to the structural PM is to continuously revise PMs to contain cross references to related, superceeding and superceeded PMs.

No comments:

PM1 - Pro Memoria - For Memory

The written word is a powerful tool for knowledge transfer to colleagues and future self. Still, documentation is often neglected in favor o...
http://formallanguage.blogspot.com/2018/07/pm1-pro-memoria-for-memory.html
formallanguage.blogspot.com
crawl=CC-MAIN-2018-43
64398
application/http; msgtype=response
sha1:BZJBE6ZMDZNEXFKHZHMYRSU2HIMOWZKC
<urn:uuid:8b04ca2f-eb48-41cc-b61a-f3efd2ba8576>
2018-10-20T02:49:12Z
172.217.7.193
text/html
sha1:WCE3HP43XC4NEO2IBQHCGTJVKGB3PWGS
<urn:uuid:b17983e5-90f7-488b-bc4b-7ecab32ca467>
http://formallanguage.blogspot.com/2018/07/pm1-pro-memoria-for-memory.html
response
<urn:uuid:b27ccddb-2be8-4095-a176-dce6fe512f48>
isPartOf: CC-MAIN-2018-43
publisher: Common Crawl
description: Wide crawl of the web for October 2018
operator: Common Crawl Admin (info@commoncrawl.org)
hostname: ip-10-168-124-187.ec2.internal
software: Apache Nutch 1.15 (modified, https://github.com/commoncrawl/nutch/)
robots: checked via crawler-commons 0.11-SNAPSHOT (https://github.com/crawler-commons/crawler-commons)
format: WARC File Format 1.1
conformsTo: http://iipc.github.io/warc-specifications/specifications/warc-format/warc-1.1/