"Be selective about what you document and what you don't."
"Documenting everything leads to noise that is a burden to maintain over time"
Whether something is worth documenting or not (why something is worth documenting):
<ul>
<li>What common questions do you spend a lot of your time answering (in active context)?</li>
<li>What information is poorly understood by your team?</li>
<li>What information is neccessary for people to make informed decisions?</li>
</ul>
"Documentation isn't free; you bear a one-time cost for writing it and a recurring cosst for maintaining it forever."

Document the right things

Understanding the reader of your writing documentation:<ul><li class="ql-align-justify">What does the reader bring to the table? What context do they have that equips them to understand the context?</li><li class="ql-align-justify">Why is the reader reading your documnetation? What problems are they trying to solve?</li></ul> Identify the target audience at the beginning of your documentation so readers can confirm reading it is worth their time (also remind the required knowledge and share links to introductory resources or summary that).New terms should be emphasized (bold) with description in footer or appedix."Bias towards simple over clever"

Understand the audience

"Structure your documentation to accomodate the different levels of investment with which readers will approach it" Each readers has their own ways to read your document (from beginning to end, skimming and dive deeper into the interesting section ...), organize your document will help them:<ul><li class="ql-align-justify">Use headings and subheadings liberally</li><li class="ql-align-justify">Add TOC to orient the reader with hyperlink for sections of the document (whenever possible)</li><li class="ql-align-justify">Keep paragraphs short; avoid "wall of text"</li></ul>

Layer your communication

"Implement practices that help your documentation age well over time" <ul><li class="ql-align-justify">Be concise. Don't repeat yourself. Maintainers should have to update the same information in as few places as possible.</li><li class="ql-align-justify">Explain why things are the way they are - help future readers decide for themselves what is still true instead of trusting your bygone context.</li><li class="ql-align-justify">Link to "sources of truth" liberally (also with references) - help maintainer update after the source changes.</li><li class="ql-align-justify">Add created time for your document.</li><li class="ql-align-justify">Collective ownership (team) over all documentation.</li><li class="ql-align-justify">Recognize contributions.</li><li class="ql-align-justify">Encourage readers to feedback.</li></ul>

Consider the future

Good documentation is essential to teams' productivity. It's hard to write documentation that is relevant, accessible and ages well over time. Everything changes time by time. Maintaince of documentation is essential to keep it fresh.

education

Learning & Education

Writing documentation for your team

"Thi thoảng bạn sẽ gặp những tình huống cố gắng giải quyết một vấn đề cả tối không xong nhưng về ngủ một giấc thì sáng hôm sau đã giải quyết được vấn đề ngay lập tức" "Giấc ngủ và các kỳ nghỉ rất quan trọng kể cả khi trong thời gian đó bạn không nghĩ ngợi gì đến vấn đề đang mắc kẹt"

Cần thời gian (thư giãn) để giải quyết những việc khó

"Cố gắng giải quyết vấn đề trong một không gian, thời gian giới hạn như các cuộc họp có thể giới hạn các ý tưởng của bạn" Sắp xếp thời gian để tập trung bóc tách đầy đủ các tình huống, làm rõ các nhiễu mà bạn đang bận tâm (việc này có thể tốn hàng giờ nhưng rất xứng đáng).Khi đi họp cố gắng cho bản thân ở trạng thái (sức khỏe) tốt nhất cho bộ não của bạn:<ul><li class="ql-align-justify">Uống đủ nước</li><li class="ql-align-justify">Ngủ đủ giấc</li><li class="ql-align-justify">Ăn uống đủ chất</li><li class="ql-align-justify">Một căn phòng đầy đủ ánh sáng và không khí trong lành</li></ul> Mỗi người có thể có những tiêu chuẩn trạng thái tốt khác nhau nên hãy làm mọi thứ có thể để bạn thấy "thoải mái" (do whatever makes you smart)

Tăng cường năng lực giải quyết vấn đề của bạn

Tìm kiếm kinh nghiệm của những người gặp vấn đề tương tự cả trong và ngoài công ty ... ngay cả ngoài phạm vi lĩnh vực bạn đang làm việc.Mọi lĩnh vực đều có những cộng đồng công nghệ riêng, tìm kiếm kinh nghiệm đã có hoặc xin ý kiến từ chính những người trong cộng động để tìm giải pháp.

Học hỏi kinh nghiệm của những người đi trước/khác

Những ghi chú khi đọc "The staff engineer's path"

problemsolving

Problem Solving

leadershipandmanagement

Leadership & Management

softwareengineering

Software Engineering

My vietnamese notes of "The staff engineer's path"

A technique that works well in a managed environment might be ineffective in a non-managed environment. Choose your preventive methods smartly (suit to your environment and hosts)

The effectiveness of prevention techniques may vary depending on the environment

CyberSecurity Incident Prevention Tips

It's OK if you're not working on the most important thing, but what you're doing should not be a waste of your time.

Know what you are doing

"If you can't explain to yourself why what you're doing needs a staff engineer, you might be doing the wrong thing"Even when you're not a staff engineer, if you can't explain (to yourself) why & what you're doing needs you, you might be doing the wrong thing.After know that what to do next is depends on you but not others but if you continue to do the same, it could kill yourself.

How to know you doing the wrong thing

"Nines don't matter when users aren't happy"                Charity Majors, CTO of Honeycomb "SLOs are useful but they don't tell the whole story"﻿You need to measure success from your users' point of view. Users/Customers could be everyone who uses your service/product.

Care about your customers

Don't forget seeing a problem doesn't necessarily mean you should jump on it.Choose the opportunities where your help is most valuable and then take deliberate action, with a plan for stepping away again afterward.

Defend your time

"be autonomous and never have to think about each other's work" ... many many ideas about your current team when you are new or you are "flying in sky" with some good moods. In reality, any big project is going to span multiple teams, departments and job functions ... Many unexpected problems (procrastination) will happen leading to miss an important deadline.

Your dream team is only in a perfect world.

<ul><li class="ql-align-justify">Understand and explain: "debug" to understand the current circumstances and "fix the bug" by make sure everybody understand the same (what's happening) </li><li class="ql-align-justify">Make the work easier: workaround by not need as much from the people you're waiting for (the procrastinating component) (reduce your expectations)</li><li class="ql-align-justify">Get organizational support: demonstrate the value of the work to get support from organization --> sometimes you need to escalate to bypass the blockage.</li><li class="ql-align-justify">Make alternative plans: change the current (origin) form of (blocking) tasks by creatively create another solution. </li></ul>

Format of techniques to deal with blockage in project.

Blocked by coding, configuration problem ... and couldn't solve it immediately, may be give you some relax could help:<ul><li class="ql-align-justify">Sleep is amazing</li><li class="ql-align-justify">Vacations can do the same thing</li><li class="ql-align-justify">Take a few days (break time) (totally) away from a problem</li></ul> You will almost come back with better ideas even if you haven't thought about it in the meantime

Give time to solve (long) blocked task

Trying to solve a problem in a narrow space between meetings maybe limit your ideas -> schedule yourself some dedicated time to (really) unpack the situation (this takes time). Bring your best brain to that meeting with yourself:<ul><li class="ql-align-justify">Good sleep</li><li class="ql-align-justify">Non-stodgy food</li><li class="ql-align-justify">Plenty of water</li><li class="ql-align-justify">A room with good light and air</li></ul>... "You should know your own problems, do whatever makes you smart"

Increase your capacity

Even you created a "best" software in the world but if users don't know about it or aren't convinced it's worth their time --> you need to do the "marketing" for your software (even internal organization) So farming, creating software may be the same, we all need to "sell" our products.

"Selling" your software / Do the marketing for your software

Don't just tell people about the existing of your solution, you need to "keep" telling them:<ul><li class="ql-align-justify">Don't assume that users will find the your product (even after you tell them about it). You need to "help them to find it".</li><li class="ql-align-justify">"Advertisement": Send emails, do road shows, get a slot at the engineering all-hands, posters.</li><li class="ql-align-justify">Support & Get feedbacks: Offer special (support) services to specific customers who are likely to advocate for you. And then get feedbacks, testimonials to understand their experiences about your products and do upgrade.</li><li class="ql-align-justify">Persistence: keep telling until they start telling each other. </li></ul>

Tell people (about your software/solution/product)

"Whatever you've created, make it easy to find" <ul><li class="ql-align-justify">Put your product at anywhere its intended users are likely to look for it.</li><li class="ql-align-justify">Make the search results on any searchable platforms reach to your product at the right place. (plan for likely names, including misspelling, mistyping and any hyphenations people are likely to guess)</li></ul>

Make your product/software/solution discoverable

"The healthy balance of feature work and maintenance work and teams build the time for high quality into the cost of their projects."<ul><li class="ql-align-justify">Make sure the user stories for the project include any cleanup work that need to do (a part of user experience or laying foundation for the next feature)</li><li class="ql-align-justify">Use related bug reports or action items after outages to justify the cleanup work.</li></ul>

(Ideally) Shipping a product is not just about the features - it's about the preparing for the future

Need a dedicated time to do necessary engineering work."There's a healthy balance of feature and maintence work, and teams build the time for high quality into the cost off their projects" Building demo versions / lightweight first verions / prototypes to get early user feedback .... take technical debts always needs us to return to improve whatever we've just bypassed. Clean up tasks should be apeared in your projects if not, it's the time to dedicate resource/plan for these tasks.

Everything comes with a price

"Software has an extraordinary number of technology areas, each with its own specialized knowledge and vocabulary. Knowing mobile development, algorithmic computer science... doesn't prepare you for a frontend UX project"﻿

Even very experienced engineers can find themselves being beginners

"... You may find that you're learning from the junior engineers you work with. (This is a good thing!) Here is where your technical knowledge provides a foundation."Even when you cannot recognize the specifics of the problems in a new domain, your general experience should help you recognize their shapes. You can pattern-match the new problem to something you recognize, so it will not be completely "new" now.The broader your scope of experience, the more "hooks" you'll hang new knowledge off and the faster you can learn new things.

Your technical knowledge provides a foundation to learn new things from junior engineers

"Know what high-quality work looks like and aim for that standard in everything you do, not just the parts you enjoy most" It means:<ul><li class="ql-align-justify">Writing the clearest documentation you can.</li><li class="ql-align-justify">Be the first person to know if your software breaks.</li><li class="ql-align-justify">Know the trade-offs: accept quick fixes (when needs) but focus on long-term solution</li></ul> How to: Having High Standards = making your work as good as it can be<ul><li class="ql-align-justify">Seek out constructive criticism - put aside your ego and ask someone else to help make you better (review, evaluation...)</li><li class="ql-align-justify">Take your comments seriously .</li><li class="ql-align-justify">Own your mistakes: admit what happened and fix , apologize... </li></ul>

Having High Standards

just my notes from "The staff engineer's Path" of Tanya Reilly

For years, companies have rewarded their most effective engineers with management positions. But treating management as the default path for an engineer with leadership ability doesn't serve the industry well--or the engineer. The staff engineer's path allows engineers to contribute at a high level as role models, driving big projects, determining technical strategy, and raising everyone's skills.This in-depth book shows you how to understand your role, manage your time, master strategic thinking, and set the standard for technical work. You'll read about how to be a leader without direct authority, how to plan ahead to make the right technical decisions, and how to make everyone around you better, while still growing as an expert in your domain.By exploring the three pillars of a staff engineer's job, Tanya Reilly, a veteran of the staff engineer track, shows you how to:<ul><li>Take a broad, strategic view when thinking about your work</li><li>Dive into practical tactics for making projects succeed</li><li>Determine what "good engineering" means in your organization</li></ul>

Writing documentation for your team

My vietnamese notes of "The staff engineer's path"

CyberSecurity Incident Prevention Tips

The Staff Engineer's Path

Tuan Tr