Daniel Pinho

§ 15 Written Knowledge

Context

Developers should strive to build Adequate Skills to perform their daily tasks more effectively. This skill-building process can stem from information from the community (per It Takes A Village) or the tool makers (per Makers' Guidance).

Problem

Different people respond in various ways to different approaches to learning. This variety can be extended to some degree depending on the situation at hand. Developers ought to assess the pros and cons of each learning approach to assert which is the best for the job.

What approaches should we take to learn more about the tools and processes in use?

Forces

  • Some knowledge, like high-level abstract concepts, can be written down and preserved, but other skills (like team dynamics) are hard to capture in writing, and are better suited for learning through experience[1].
  • Written knowledge provides developers with information that can be revisited when needed, but creating and maintaining these materials takes time and effort[2].
  • Prior knowledge can help developers understand some written material more easily, but some background knowledge can also bias the developers’ interpretation of the material, leading to misunderstanding or overlooking ideas.

Solution

Expand your theoretical knowledge through written sources of information, such as reference documentation, books, guides, and tutorials.

Written tutorials, documentation, and textbooks are commonly used knowledge sources for developing programming skills[3]. They provide a structured view of the topics being studied. Unlike other approaches, such as classes or in-person interactions, developers can work through them at their own pace and go back and forth on the material as needed.

Depending on what the developer is working on learning, they can often find examples[3] in their materials, which effectively transmit concepts[4][5].

Written information can come from myriad sources, such as: from the developer’s team as a source of intra-project or intra-organisation documentation (see §8 Team Players), from the community as tutorials about a programming language or even books about programming concepts (see §16 It Takes A Village), or from the makers of tools used by the developer as official documentation (see §17 Makers' Guidance).

Written information can also be easily consulted at a later time, enabling developers to refresh their memories on concepts and ideas as needed.

Examples

  • Language and framework documentation pages provide developers with a formal overview of the capabilities of the tool in question, touching upon topics such as syntax, functions, and other usage information[6].
  • Internal documents, such as ones detailing specifications, design documents, and architecture diagrams, are useful to disseminate knowledge within the organisation, facilitating communication and easing comprehension of the code base[7][8].
  • Technical magazines and blogs provide developers with ways to stay in touch with rapidly evolving technologies through the articles they can find within. These often focus on tutorials, documentation, projects and other technical discussions[9].

Consequences

  • Written materials enable developers to learn more about different concepts and can be revisited when needed, helping with retention.
  • Teams can use documentation as a shared reference point, and their use enables their alignment in terms of knowledge on common areas.
  • Written knowledge can become outdated, and relying on it without ensuring it is up-to-date can lead to misconceptions.
  • Reading does not support the development of tacit skills on its own, as it is not a source of first-hand knowledge. Developers should complement this learning approach with other methods, such as with Practice Makes Perfect and Learning From A Master.

Compare and contrast with §13 Practice Makes Perfect and §14 Learning From A Master, which outline other methods of learning.

The patterns §16 It Takes A Village and §17 Makers' Guidance provide information on sources of written knowledge.

References

  1. I. Nonaka, “A Dynamic Theory of Organizational Knowledge Creation,” Organization Science, vol. 5, no. 1, pp. 14–37, 1994, Available: https://www.jstor.org/stable/2635068
  2. J. P. Walsh and G. R. Ungson, “Organizational Memory,” The Academy of Management Review, vol. 16, no. 1, p. 57, Jan. 1991, doi: 10.2307/258607.
  3. J. Escobar-Avila, D. Venuti, M. Di Penta, and S. Haiduc, “A Survey on Online Learning Preferences for Computer Science and Programming,” in 2019 IEEE/ACM 41st International Conference on Software Engineering: Software Engineering Education and Training (ICSE-SEET), Montreal, QC, Canada: IEEE, May 2019, pp. 170–181. doi: 10.1109/ICSE-SEET.2019.00026.
  4. E. Lahtinen, K. Ala-Mutka, and H.-M. Järvinen, “A study of the difficulties of novice programmers,” SIGCSE Bull., vol. 37, no. 3, pp. 14–18, Sept. 2005, doi: 10.1145/1151954.1067453.
  5. K. VanLehn, “Cognitive Skill Acquisition,” Annu. Rev. Psychol., vol. 47, no. 1, pp. 513–539, Feb. 1996, doi: 10.1146/annurev.psych.47.1.513.
  6. M. P. Robillard and R. DeLine, “A field study of API learning obstacles,” Empir Software Eng, vol. 16, no. 6, pp. 703–732, Dec. 2011, doi: 10.1007/s10664-010-9150-8.
  7. S. Baltes and S. Diehl, “Sketches and diagrams in practice,” in Proceedings of the 22nd ACM SIGSOFT International Symposium on Foundations of Software Engineering, Hong Kong China: ACM, Nov. 2014, pp. 530–541. doi: 10.1145/2635868.2635891.
  8. O. Manai, “How software documentation helps communication in development teams: A case study on architecture and design documents,” University of Gothenburg and Chalmers University of Technology, Gothenburg, Sweden, 2019.
  9. C. Parnin, C. Treude, and M.-A. Storey, “Blogging developer knowledge: Motivations, challenges, and future directions,” in 2013 21st International Conference on Program Comprehension (ICPC), May 2013, pp. 211–214. doi: 10.1109/ICPC.2013.6613850.

Last updated: December 18, 2025