Let's audit our current/old engineering docs and spin up a plan for things we need to move/modify/add

pirog commented 5 years ago

What is to be done?

We have moved and updated some old engineering docs to this new docs site: https://docs.thinktandem.io/guides/ We also have a bunch of older "engineering" docs spread throughout the old docs site (u: tandem, p: tandem). NOTE that "engineering" docs are not necessarily confined to the "writing code" section of the older docs. https://docs.v1.thinktandem.io/

We need to audit the new and old materials and determine what things need to be updated, moved over to the new site (or not moved over), how they should be organized, etc. For things that do require updating (eg are no longer in line with on the ground practices) we need suggestions for updating those things. We also might want to recommend/suggest any obvious "gaps" in our engineering docs/guides eg things we might want to make in subsequent tasks.

This task should end up with basically audit recommendations and new follow up tasks to implement said recommendations. That said, we are not looking to make HUGE changes right now, let's just "get things in order and alignment" and set a new foundation. If there are "big" recommendations they can be converted to discussions for a later time.

Task checklist

[x] I'm aware of what a task actually entails
[x] I've selected at most two labels that best describe what part of the business this ticket improves eg sales, dev, etc
[x] I've added a story point estimation. This should never exceed 3!!!
[x] I've created a follow up task or discussion and linked to it in the section below or labeled this as a "one-off" task if there is no follow up task
[x] I've also gone into any applicable follow up tasks and set this issue as a dependency

Next steps(s)

One of the purposes of this card is to fill out this section

mikemilano commented 5 years ago

@pirog this is pretty abstract so we probably need to meet to discuss.

I believe #2 is related and we should consider better defining, or enhancing the git workflow.

pirog commented 5 years ago

@mikemilano alright

pirog commented 5 years ago

@mikemilano so i also scanned through the old engineering docs and the only obvious thing i saw that looked worth moving into our new docs was https://docs.v1.thinktandem.io/coding/guidelines.html#guidelines

A bunch of the other docs looked like they might be better served/encapsulated in various seeds/start states

https://docs.v1.thinktandem.io/coding/common-tools.html - presumably almost all our projects are generated from a seed or start state so a good deal of these common tools we "just get" by using the start state. i could see a space for "common tools" we use to augment projects spun up from start states but this feels potentially brittle and hard to maintain. it might be better for us to have a "policy" around choosing modules/plugins/etc instead of a whitelist of things.
https://docs.v1.thinktandem.io/coding/devops.html#setting-up-a-project - i think ideally this is also just baked into each seed so once you spin up a new project you've got a few commands you can run to spin up the devops, lando, platform.sh etc

I think all of the other "engineering" type docs beyond those seem like they are either too brittle or likely-documented-better-elsewhere to be worth keeping. Eg there has go to be a better article than something we've written to describe something like https://docs.v1.thinktandem.io/coding/styling.html#extends-vs-mixins-%E2%80%94-the-battle-royale, and im ditto for a good deal of something like https://docs.v1.thinktandem.io/drupal-wp/drupal-8-accessibility.html

Anyway, hope that helps!

mikemilano commented 5 years ago

Recommendations:

Guidelines:

Copy it over, as-is. This is a good doc. As noted in my original review, it might be able to be made more concise, but I'm not sure the effort to is justified based on that alone.

Common Tools:

I agree that this should be more of a policy, and if so, does it belong more in "Guidelines"?

A list of common tools and start states however would be valuable. I'm not sure if that belongs here, or in an external project, but it might make sense to assign "Tool & Process Maintainer" for each type of tech, and allot that person the responsibility to keep the list of tech for that area up to date.

i.e. Drupal: John Vue: Dustin Node: Mike P

Common tools can be suggested in Slack
A couple hours bi-monthly (or whatever frequency makes sense) will be scheduled for each maintainer to audit the list for relevancy
Changes will be announced at a specific frequency with all other Tandem business changes, if we end up setting this up.

Conclusion:

Determine if having maintainers makes sense.
Determine where the list of tools per technology type lives
Refactor this section to document the maintainers and process
Document the list of common tools wherever it is decided to live

Setting up a project

At the very least, the platform.sh link needs to be updated as it points to a deprecated repo.

This feels pretty light, but I suspect it would take some work to figure out how to articulate when we may use travis or circle ci, when we use one over the other, and then more detail on how to set those up.

We also may want to break this up into the "tech types" as they are in the common tools section, and since project setup may change as tools or config changes, we may want to use a similar "maintainer" process to keep the setup documentation in check.

How often are we setting up project? The answer to this should weight into how much attention we give any changes here. What is there may be sufficient with current external links.

pirog commented 5 years ago

@mikemilano im going to close this out and spin up more narrow and actionable tickets based your comments

thinktandem / tandem