chairleader

Documentation is only good if you can find it again when you need it.

Does anyone have a good pattern for documenting the things the team will need to have to build and deploy working software? I assume for this discussion that we are capturing documentation in a hierarchy such as a wiki or folders of Markdown docs. I'm looking for a pattern that works well for teams both in finding the information and in contributing to the documentation.

Key things I find myself needing at key times include these and countless others: - requirements / constraints behind decisions so that when changes are needed we don't backstep - runbooks for special cases during deploys - runbooks for onboarding new teammates - introductory reading for new teammates

My best bet so far has been to try to group things by the context of their use. By this I mean first group by the role one is assuming when they are looking for information, for example "Operations," "Architecture," "Contributing," and group things below that as best I can.

I find this has its challenges for teams to get onboard with since it is a bit subjective, and most people don't seem to think about wearing different hats in this way.

This also hits a limit when you fold in project planning: documenting things that _may_ come to be part of the software when (and if) work is completed adds a great deal of complexity.

What has worked for folks here? Are you using other tools and processes to replace some of these documentation needs?

I am a professional software engineer who has spent most of his 20-year, post-college career in interpreted languages. As much as I love never having to think about pointers or threads, more and more I bump up against the wall of what's possible in these environments - I only get to use low-level services like graphics and audio or cutting edge solutions like WebRTC if someone kindly wrote and maintained native bindings in my languages of choice.

Enough! It's time to take the plunge!

From my armchair, it looks like I'll need to pick:

* compiler * build system * linter and other tooling * standard libraries

I am all for standing on the shoulders of giants... I want to build non-crappy software that does meaningful things with the best tools.

What pieces should I put together?

FWIW, I'm seeing great threads on learning C++, but don't see a toolchain convo. Feel free to correct me!

- https://news.ycombinator.com/item?id=23380537 - https://news.ycombinator.com/item?id=20252926 - https://news.ycombinator.com/item?id=16535886

Dealing with faults is easy: read the stack trace and stop doing what shouldn't be happening. But what about errors where something should be happening but isn't?

For example, I might have a notification system where users are reporting missed messages. They give concrete examples and I can verify that, given the state of the system, the notification should have been sent, but evidently it hasn't. This involves multiple systems, changing state and many potential failure points. This is a legacy system written by others, so I have an incomplete mental model of the system, and obviously can't reproduce the error.

I'm an experienced software developer, but whenever I encounter an error like the above, my steps include: * Backtrack from where something is supposed to happen looking for potential logical bugs. * Add more logging * repeat

It's not very efficient! I'm tempted to throw the system out and replace it, but we all know what kind of a trap that is.

So how do engineers here attack a problem like this? Are there activities you do, e.g. building flow diagrams, that help guide you through the process?

It seems natural that a startup with a small team forego traditional project management in favor of delivering the product. However, at a certain scale, project management components start to become critical. For example, I expect that when well executed, following practices would save months of time:

  * Domain experts sign off on a plan to ensure success
  * Stakeholders agree that their needs will be met
  * Just enough design and estimation is done to plan around dependencies

My question is, who out there is getting project management right? What does it look like inside the organization - what responsibilities do engineers, managers and product managers have in order for this to work? Has anyone seen a firm successfully adopt a culture of project management?