www.rozumim.cz

Knowledge base

There are only three short posts in the series “What I have learned” (1, 2, 3) and you may be wondering:

Hey Petr, haven’t you learned anything recently?

Well, of course I have! But I found a more convenient place for me to write about it: a GitHub repository.

Why am I doing it?

When I encounter some problem that takes time to figure out and after solving it I feel like I may need that answer one day again, I write it down.

It’s something I learned in my previous jobs. That GitHub repository is actually only the latest of the knowledge bases I’ve created (and the only one publicly available). In my two previous jobs I was working on systems that both already existed for some time and there was a lot to learn. Some problems and questions came up again and again so instead of relying on my memory I started to write things down.

Good topics for a knowledge base

  • Dev environment setup
    • Versions of libraries and software you use.
    • Common errors during setup and their solutions.
  • Configuration
    • Location of config files (can be tricky when you are developing a desktop app).
    • Sample values for different settings.
  • Architecture
    • Modules, their responsibilities and interconnection.
    • Important classes.
    • Interesting tables in the database.
    • How the application runs in production (servers, databases, …).
  • Application flow
    • How is a request handled by the application.
    • How the application deals with errors.
    • How checking the rights of a user works.
  • How-to
    • How to add a new page to the application.
    • How to query a database.
    • How (and what) to log.
    • How to access logs from production.
    • How to upgrade a database schema.
  • Tools
    • IDE setup.
    • Version control conventions.
    • Tips for more productive and comfortable work (e.g. keyboard shortcuts).
    • Command line tools and their usage.
  • Repetitive tasks
    • Building a new version.
    • Running tests.
    • Changing certificates on the server.
  • Terminology
    • What does “window E” means? (Editor!) What is a “site”?

Yes, most of it should be part of a documentation, but is it?

You can do it too

Start simple. If you have a wiki, create a page there, if you use GitHub, there is a wiki already. The key requirement is that is has to be really easy to edit. And the second most important thing: it should be easy to search through. If you publish it online, you can link to it and share it with your colleagues. I would suggest you not to think too much about a structure. It will naturally happen as the knowledge base grows.

30. 7. 2017, kategorie:
comments powered by Disqus