Ask HN: How do you organise and discover your team's internal scripts?
As a team we have many scripts for doing various internal tasks - domain-specific things, checks for questions like "what's in prod?" and "how far along is this commit?", etc. ad nauseam.
The problem is that, with a few exceptions, the person who wrote the script knows it exists and how to use it; and might be around to chime-up with "hey, I wrote a script for that!" when someone has a problem.
But discoverability is hard, even if they're in the repo not everyone will have seen or reviewed the PR that added them.
Does anyone have some good tips to share on how to (or not to) organise such scripts or tools, and allow colleagues to better discover them?
48 comments
[ 3.5 ms ] story [ 13.8 ms ] threadIf you did it, document it.
Make sure that what ever tool your using for documentation supports full text search, and tagging.
Any suggestions?
This way documentation changes go through the same code review process as actual code, and actual code pushes can be linked directly with changes in documentation.
You can document all you want and it won't matter if no one is looking in the right place. I think that is really the root of OPs question.
At the companies I've worked at, I've seen utility scripts stored in the main repo with the code, in their own repo, in a gist, in confluence, in Google docs, and in OneNote. Often the same company is using more than one of these at the same time. It's like one person gets fed up with the current solution not doing what they want and decides to create their own standard. BTW, I'm not condoning any of these, it's just what I've seen over the years.
I'm a firm believer that if you give people a solution that is easy to use and meets their needs, eventually they will gravitate toward it. On the flip side, if a solution is complicated or useless, they will eventually stop using it, even if it is company mandated.
From what I've seen, all these solutions are either overly complicated or don't fully meet a companies needs. I think OP is looking for suggestions of tools that other people use and like, so they can try it on their team.
Let's say our project is called cob, so typing `cob` would print a help screen of all the tools it knows about. typing 'cob db' would show all of the tools in the db namespace. For simplicity there is only one level of namespaces allowed. Anything under that is a command in that namespace - eg 'cob db recompute_index --column=foo' to recompute an index, 'cob deploy show_live_version --prod' to show whats in prod right now, etc.
If you're doing a task and think a tool might be available, searching through a limited set of tools based on the likely namespace and with simple help text makes it easy to find.
I live in a world where we're expected to be synced to head in a monorepo, so distribution is easy for me.
- The Jenkins job can have a friendly name, a description, a link to wiki article explaining how it works, and default inputs.
- Troubleshooting wiki articles also link back to the job (_"Getting this error? Try running this job"_)
- We don't need to worry about people having prerequisites on their machines (assuming they are installed on the Jenkins runner). They shouldn't even need to understand the language the script is written in, or how it works.
- You've got the opportunity to integrate and chain jobs together, or trigger them based on events.
- Pretty much everyone knows how to create and run Jenkins jobs
Of course having solved one problem (discoverability and organisation of scripts) you now have another one: Jenkins.
I called this phase 2. Discovery, documentation and ongoing maintenance going to be the problem. We need to another jenkins to CI/CD the main tooling Jenkins.
My other though is that there is significant market for this kind of back office tooling clean up and ongoing maintenance. If we could come with a process to clean up and package it. we could sell it. I would definitely buy it cause it gives lot of time saving for day to day toils especially in operational space.
For both, you install a local agent that polls the website for commands. You can manually kick off a “deployment” that just downloads and run scripts. Both have agents for Windows and Linux.
VSTS is free for private environments for five users and like $5 a month for additional users for one simultaneously running agent - you can have as many agents as you want installed but only one will deploy at a time. Additional simultaneously running agents are cheap or free for each registered MSDN subscriber who is a user.
AWS Code Deploy is similar. It’s free for AWS hosted EC2 instances and a 1 cent for each on prem deployment.
They both support the concept of deployment groups where you can run the same deployments on a group of machines.
Code Deploy uses a simple YML file that tells Code Deploy which scripts/batch files to run.
They both support integration with GitHub via webhooks.
- Jenkins can manage credentials and inject them into your script, so you don't have to expose them to the user or put them in source control.
- You can easily add lots of helpful things like email and chat integration (e.g. have a job yell in Slack if the script fails).
- You can integrate Jenkins with Active Directory and require a user to be in a particular group to trigger a job.
- Jenkins gives you a centralized place to record audit logs of who invoked what.
Jenkins can be a pain to learn and manage, but its super powerful and worth while.
We've started adopting the `s/` method described here by Chad Austin: https://chadaustin.me/2017/01/s/.
It means you always know where to look and it's easy to see what scripts exist.
For instance, I know this one guy is good at Dev Ops. I send him a ping asking a question, he forwards me to the other guy.
That's the most efficient way I've found after years of development...
I ensure my management team understands and sees how many people I help. If I can spend 5 minutes several times a day - each time showing someone where a script is that saves hours.. well I've just saved the company a lot of money.
- Each project has a "scripts" folder with utility scripts and there are playbooks in Confluence on when and how to use them.
We use a private wiki grouping how to's, scripts, guidelines.
1) a git repo in an obvious place
2) a shared drive in $PATH
even better, a share controlled by a git repo.
1. Good software engineering is about writing tools (scaffolding) around the main project (sistene chapel). If a team is not putting in something like 1/3 to 1/2 its time on tooling it is probably being pushed too hard or seeing too many of the other project warning signs we all know and love.
2. Social contact and pride. If devs have plenty of time to write their tools, then they get proud of them, make the more generic and usable and they start to market it (hey I have a script that does this is marketing as much as OSS ) Brown bag lunchtime sessions seem the perfect way to encourage this - At a Big Bank we had a kind of show and tell for internal scripts for a while.
3. This is what senior devs, tech leads, what have you, should be doing - talking amoungst themselves and emerging the critical missing parts in the company (besides recruiting and code reviews). Again if they are not - it's a sign of too much pressure, too much silo'd working.
In the end I have some code I happily tell people about and encourage them to use - because I have invested the time to make it work well, and if I have not, I don't coz its embarrassing.
Fix the management / time / good engineering problem and you will find the scripts being shared in the canteen.
Of course fixing that is not something you have authority or influence to do. This could be a problem.
If you have the time and motivation to write an internal tool, you should also have the time and motivation to write down the how and why.
If you want to make a tool a part of your process, document that process and where to use the tool.
So, each project has its own set of aliases and utilities in the repo.
It's not the cleanest thing to do, but it works pretty well.
[1] - https://gist.github.com/rlopezcc/7d545a2b09a9c7a391483608a51...
Edit: Formatting.
The (idealistic) answer, is that when a given script finds more than a few users, or even gets used more than a handful of times ... it should be incorporated into, and formalized, in the system. Make an admin panel/portal/dashboard, put a UI in front of the script for any variables, and make it so that this function doesn't require cryptic institutional knowledge to execute.