Code Monkey home page Code Monkey logo

document-shredded's Introduction

Hi there ๐Ÿ‘‹

This is Yaobin, a software developer. Happy Hour ๐Ÿป is my personal task tracker.

What kind of person I am

I always try to understand the internals of the technologies. For example:

  • yaobinwen/ssh-tunneling-explained explains what SSH tunneling is and how to use it.
  • yaobinwen/cpp-static-dynamic-linking explains how GCC static linking and dynamic linking should be configured to work.
  • yaobinwen/git-log-S-G explains how git log -S and git log -G work using the repository itself as an example.
  • yaobinwen/backporting-gl2ps discusses the issue I ran into when backporting gl2ps from Ubuntu Impish to Ubuntu Bionic by looking deep into two packages: debhelper and CMake.
  • To verify whether I truly understand the technologies, I try to explain them in my own words. Therefore, I maintain my own tech blog at yaobinwen.github.io which discusses computer-related technologies, including explaining the topics I've just learned in my own words. This serves two purposes: I can verify if I truly understand the topics; the readers can learn the topics more easily.

I am willing to dive into the source code in order to understand the magic behind the scenes. For example:

I always try to prioritize learning the fundamental knowledge over the high-level, trending technologies.

  • By "fundamental knowledge" I mean as follows:
    • Operating system (this is why I started the learn-linux-kernel project)
    • Networking; TCP/IP
    • Data structures and algorithms
    • Mathematics (this is why I started the yaobinwen/Robin-on-Math project to re-learn math after leaving school for many years)
    • etc.
  • This doesn't mean that I don't want to learn the high-level knowledge. It just means I believe grasping the fundamental knowledge can boost the learning of the high-level knowledge.
  • Also, trends come and go; fundamentals stay.

I am a good team player because I am willing to step out of my comfort zones to work on the tasks that require the technologies even if I have zero experience before, as long as the team need.

  • This team-oriented spirit gives me the opportunities to use a broad range of technologies from the low-level ones (e.g., Linux kernel, system administration) all the way up to the high-level ones (e.g., React.js). This gives me the chance to learn how to develop a full product and also allows me to work on a wide range of things that can support the team better.
  • However, I am also aware that the disadvantage of working on a broad range of technologies is it's difficult for me to become really good at one specific area. I have to admit this is probably the inevitable loss when I enjoy the gain.
  • But I do have my preference: After working on various technologies, I want to spend more time working on the system-level technologies such as Linux kernel, C/C++ libraries, networking, etc. (This is why I started the project yaobinwen/learn-linux-kernel to learn Linux kernel.)

I learn by practicing, so I have a few "sandboxes" that allow me to experiment with the technologies I'm learning. For example:

  • yaobinwen/web-box is the project I use to learn web technologies of the following:
    • Raw HTML + CSS + JavaScript
    • node.js
    • React.js + MUI
    • Tornado web server
  • yaobinwen/robin_on_rails contains the notes or thoughts that I took when I read technical articles. The notes and thoughts in this repository may not be well structured yet,and my plan is to gradually turn them into articles once I've accumulated enough in the related topics. The repository also includes a few folders for experimental code, such as:

I always try to communicate as clear as possible. This includes writing clear and easy-to-follow documentation.

  • I have to admit that writing good document is a difficult task. This difficulty motivated me to start the project yaobinwen/document-shredded which collects documentation good practices with examples and bad practices with counter-examples in order to create a repeatable process of creating easy-to-understand documentation.

I track my time usage so I can tell where I spend my time. This gives me a few benefits:

  • I can tell whether the way I spend my time aligns with my goals. For example, if my new-year resolution is reading more, but I only spend one hour per week on reading after 3 months according to my time tracking log, obviously I'm not achieving my goal. Then I can figure out why I didn't spend enough time on reading. Maybe I didn't build up the habit yet, so I need to make personal adjustments; maybe my goal was not feasible in my current situation at all no matter how hard I work on it, so I need to adjust my goal. Either way, I wouldn't be able to get the insight without time tracking.
  • I can tell my actual time of working on development tasks, e.g., 70%. This allows me to make better estimates on future tasks so I know if my estimate of a task is 1 day (assuming 8 hours), I may actually need about 1.5 days to finish it.
  • Example snapshot of my personal time tracking (using Toggl):

time-track-personal

  • Example snapshots of my time tracking for work (using Google Sheets and Xpad for simplicity):

time-track-chart-histogram

time-track-chart-pie

Other repositories

  • yaobinwen/work-env contains the scripts, guides, and programs that help me quickly set up my own work environment.
  • yaobinwen/local-https: Deploy a local HTTPS web service which is good for local testing and experimenting.

document-shredded's People

Contributors

yaobinwen avatar

Stargazers

 avatar

Watchers

 avatar

document-shredded's Issues

Ansible doc: action plugins and modules

The action plugins are run in the context of the user that launches the playbook so it is not affected by --become. Is this documented anywhere?

  • Maybe I can ask on the #ansible channel.

A book for learning general programming

I may write a book for beginners to learn programming in a general sense, not about a specific language.

Then once the beginner gets some experience, he/she no longer needs to read a book as fluffy as The Go Programming Language. He/she should be able to grab the language reference or cheat sheet to learn the language quickly.

The Go Programming Language sins:

  • It spreads important points among texts without emphasis so I have to use a highlighter to mark them by myself.
  • Most of the time, it talks the easy topics that any experienced developers can learn in half an hour, totally, but I'll have to go through the whole text to make sure I don't miss anything important, especially those language features that are "similar to another language but not the same".

Collection of loss of knowledge

Description

This issue collects the cases of "loss of knowledge": Because programmers come and go, when a project has been ongoing for quite a long time, the knowledge of some part of the code may get lost along the way.

It needs further evaluation to see if this is caused by lack of good documentation, but usually that means the implemented feature is not important in practice so nobody really cares.

`amixer` documentation

Description

amixer documentation may not be good enough. Take this question for example:

Why do we supply pulse as a parameter in amixer command?I have noticed if I doesn't supply pulse parameter to amixer command it doesn't work and throws error.

However, the owner of the answer didn't reply it. I have the same question. Unfortunately, I don't seem to be able to find the answer with some quick search (e.g., amixer(1)).

Another question is: What is the Master control in amixer? There doesn't seem to be an answer about that. amixer(1) has an example that says:

amixer -c 1 -- sset Master playback -20dB

will set the master volume of the second card to -20dB. If the master has multiple channels, all channels are set to the same value.

which seems to suggest that Master is a special control that covers all the available "channels".

The article A close look at ALSA has a section "ALSA concepts" which explains "cards" and "devices", but it doesn't explain what the Master is.

Anyway, I think many open source projects need to build better documentation in order to transfer knowledge.

HTTP caching

HTTP caching

Today (2021-05-04) I tried to learn about "Heuristic Freshness Checking". This page refers to RFC 7234 Section 4.2.2, but I find this section doesn't provide any specific example so it's hard to understand how it is calculated by simply reading the text.

Some other references I can take a look:

Doc smell: infinite links which means one resource provides a link to another resource which provides a link to a further resource but none of them explain the things clearly enough.

Counter-example: CMake (3.21.3) tutorial

CMake 3.21.3 tutorial does not provide a link to the accompanying source code, or at least the link is very difficult to find unless I search it in Google (and the repository is not even the top results in Google search results). However, the tutorial itself refers to the code frequently and makes me frustrated not to be able to read the code while reading the tutorial.

FYI: The code is here.

Think about "knowledge sharing driven programming"

Very immature idea but basically:

  • We write code in the way that's easier for sharing the knowledge: future developers should not spend huge amount of time to learn it.
  • Documentation generation should not rely on the particular format of comments because comments can be out-dated.

Write about what makes good documentation

Goals of good documentation:

  • Minimize the time that new readers need in order to grasp the related topics.

Good documentation should include:

  • Background: Why is it?
  • History?
  • Cookbooks: task-oriented
  • FAQ
  • Security Concerns
  • Main Body of Knowledge
  • Comparison of similar technologies: pros and cons
  • How (for developers)
  • Ecosystem: How this technology is related with other upstream/downstream technologies
  • Examples vs abstract description
  • Best Practices

Good documentation tells EVERYTHING about the software. However, this is almost impossible because chances are the developers themselves do not have a total grasp on the software: it's just too complex.

React Router updates API (replacing `Switch` with `Routes`) without explicitly mentioning it in the documentation

See this Stack Overflow question and one of the comments.

Actually, it turned out to be that React Router v6 is quite different from the earlier versions and they published the documentation for v6 here. Technically, they didn't do anything wrong. However, they probably should have mentioned in the documentation website that v6 is quite different so the users should pay attention to the version they are using.

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.