Thanks for the reply, I'm also a big fan of documentation living inside the repo. I appreciate the framework you describe for the readme as well. Similar to _kb's sibling comment, that sounds like a sane approach to meeting the needs of contributors to and supporters of the codebase.
FWIW, I'm struggling with documentation that support the mix of roles on the team in addition to coders/contributors - QA engineers, product owners, project managers, support teams, etc. A big part is the capture of requirements flowing into proposed solutions and out into support documentation.
In reply to _kb, it did occur to me that there are many job descriptions at play here, and that change is inevitable. Perhaps the answer is simply that it takes many people and several genres of software to keep things from falling through the cracks.
Thanks for this link, I agree, that is a fantastic framework for documenting software.
The idea that a reader of a piece of documentation is approaching it with a particular goal is spot on. I suppose I envision either more or perhaps another layer of goals/contexts in addition to what this is outlined here.
A set of use cases I'm thinking of involve the process of changing what a piece of software does. As design documents arise that may or may not apply to a future version of the software, where should that live? Perhaps during the design phase of that release it belongs in one place while designers are iterating on its contents, and later it moves to another place
when it is considered a stable reference document?
Plenty of capital P Process behind this question, I suppose. And perhaps there's no getting around some amount of the "librarian" work moving content around to reflect its use.
The symptoms we experience are: - not capturing key information, often because the challenge of finding a place makes a project out of a task which then gets dropped, - capturing the information in an island somewhere making it unfindable later on, e.g. a loose document in a user's Confluence space.
With a team of folks with different skill levels, when there's information to capture, I'd like there to be a clear single place for it to live so that it's easy to place there and easy to find again.
Interesting. I would say that John didn't build a solution that met all of the use cases that the business needed.
* To ensure accuracy of transactions, he should have built reporting to meet the needs of accountants.
* To support change, he should have kept his components separate and provided modest testing examples.
* To support developers and operations, he should have found and documented the external dependencies along with steps to verify that they are in place.
Whether product managers didn't uncover these requirements or the business didn't prioritize them, these aspects of the definition of "done" have more to do with thee environment the engineer is working in and less to do with his or her work.
> In general, reviewers should favor approving a CL once it is in a state where it definitely improves the overall code health of the system being worked on, even if the CL isn’t perfect.
Reviewers are human too, and can occasionally get lost in the weeds nitpicking a PR/CL.
What tends to be the first indication of breaches? It's one thing to do a forensic analysis after learning of a breach, and it's another to detect it in the first place.
I'm working in a vanilla PHP codebase right now, and I see all sides - the fractal design fails and the surprising improvements to the language. I've just read up on the architecture of Laravel, and given the public opinion of it, must be a very nice framework.
What strikes me most about PHP is the fundamental request/response execution model. Your execution context begins when a request is received and ends when we send the last byte or terminate the request. There's no startup healthchecks, no cache warming or any other bootstrapping of your service unless you jump through convoluted hoops on your own. Your service is either accepting requests or it isn't. You either lazy load your data into APCu or you don't. I've leveraged AWS healthchecks to achieve these in the past, but that path is not very maintainable.
Inevitably in the course of maintaining a service, I find use cases for a phase of execution that should occur before the server is live or shared static memory that should be available at all times, but (unless I don't know something) those are things that PHP doesn't do.
This is the reason that I find PHP to be a bizarro language - for its fundamental design assumption!
til! Most of my experience with large, single-repository projects are just plain monoliths. The design goal we strive for tends to be the microservice architecture, assuming that isolation of responsibility leads to more maintainability, better decision making, etc. I can see how, with a well disciplined team, the monorepo could have the best of both worlds.
Quite a premise: "Giant monolithic source-code repositories are one of the fundamental pillars of the back end infrastructure in large and fast-paced software companies."
Interesting. Are you going with an established project management framework or introducing practices gradually?
I agree with you about the value of training... adopting these practices should come with a change of mindset since good judgement is required to succeed in practice.
Worth noting that I find the flow state far easier to enter at different times in the day. Between around 2:30 to 4:30, I find it very easy to immerse in a task, to the point where even if I _should_ switch to a higher priority task, I will most likely stay on the track I'm on.
Who knows if that is circadian rhythm, conditioning, a combination of both...
Some great tips and tactics here. I think it's worth describing the end-state you might be shooting for which those tactics can help with.
From what I'm reading, I think you're looking for the ability to deeply immerse in problems when the time is right.
When you're deeply immersed or in a flow state, your conscious and unconscious are completely aligned on a common goal. In fact, your conscious mind participates less and less in the tasks - only providing high-level strategy notions to your work, letting your subconscious tactical problem solving, recall and muscle memory do the work of getting the solution out into the world.
When it's working:
- your working memory (i.e. the classic 7+/-2 figure from psychology) is filled with the task at hand, and nothing else. Not only are you not thinking about other things, but you also have no doubts or second thoughts about what you're doing or how you are doing it.
- you have short feedback loops in place, letting your brain's pattern recognition work effectively.
- you have all of the tools you need at hand to solve the problem, and don't need to switch tasks to build/acquire them.
When you're in this state, you don't need a dopamine rush from anything else - you're caught up in in the problem, and don't need something to synthesize the excitement of discovery. You're getting that from the task!
Conversely, some examples of how it can break down:
- The steps required to reproduce your test conditions overflow your working memory, especially when decisions or analysis is required. Any conscious thought put towards the steps to recreate a test case is a task switch away from the problem you're solving. You might want to invest in scripts to automate some or all of the work.
- you're not sure if your approach is the right one. Now you're spending some of your problem solving energy on the "meta-problem" of how best to solve the problem. Take a moment to prove to yourself that the approach is at least worth investing in and then move forward.
Finally, know that deep immersion has its own drawbacks! Most importantly, while deep into solving one problem, it's easy to "over-invest" by going down the wrong path. For now, you might consider that a good problem to have and a sign of success at acquiring this skill. Honing the skill of choosing between the two approaches is level 2 ;)
Good point. Dimensional analysis is a great "space" to traverse to get answers. It's a great grounding for your thinking, in addition to helping you get to within the right order of magnitude.
I suppose I was wondering if there are any good drills, exercises or puzzles to help internalize these skills. Instead of a daily crossword, maybe there's a daily estimation puzzle somewhere.
Any resources for learning the Fermi estimation techniques listed there? Seems like a collection of complementary skills, each of which could be improved:
memorizing useful facts, selecting facts that lead to a meaningful estimate, the mental math to compute the final result