I've enjoyed the video course from How a Car Works [1]. They assemble a complete car from scratch, so you get to hear and learn about pretty much every component.
363 karma · joined February 14, 2017
The team I worked with in my previous job built a lot of tooling around OpenAPI (CLI, GitHub integration etc.) to try and improve the developer UX around creating, maintaining, and collaborating on large definitions. The OAS definition for the company's core product amassed ~60k lines of YAML. Some of the features you listed happen to solve some of the biggest challenges we ran into:
> Type checks and autocomplete.
The CLI tool we developed was able to parse an OAS (expressed in a single file or over multiple ones using $refs) into a tree structure. This allowed the tool itself to reason about the state of the OAS, but it was difficult to expose the same information to the user via an editor extension or language server.
Utilising an existing language and all of its editor features to write the OAS to begin with would alleviate some of the pain points we saw when managing very large collections of OAS files.
> Easy CICD integration.
We built a whole GitHub integration that listens for webhook events (like PR opened, commit merged into master etc.) which then downloaded the OAS files from the affected repo, ran checks and validations, compiled them into a single monolithic file, uploaded the file to S3, and generated Markdown docs. I can imagine this process being much simpler if existing language tooling is leveraged.
> Git-friendly.
Definitely something to think about at scale.
> Live-reload preview though webpack-dev-server or similar.
We attempted a VSCode extension which ran the CLI tool in the background. It watched for file changes, attempted to parse them into a complete OAS definition, and then generated Markdown docs into a temp directory and invoked the Markdown Preview extension to display a live-reload preview. It worked most of the time, but using webpack-dev-server seems to be more fit-for-purpose. You would certainly have more flexibility in how the docs are generated; whether you want a basic Markdown to HTML rendering or throw the OAS into ReDoc or something.
Other aspects I reckon are worth thinking about:
- Contract-based testing. We added custom properties to our OAS files so teams could define test examples and scenarios in YAML. It was terrible to work with as YAML doesn't give you the amount of flexibility you need to define rich and varied test cases. I imagine this would be simpler in TS. - Shared schemas and examples. You might have this in mind for the "Support for js modules and npm packages" feature, but a nice mechanism for defining and consuming shared schemas would be awesome. Maybe these could be published as NPM packages?
Some interesting points you raised:
> I don't like generating it from code either because it tends to clutter everything and devs usually get too confident and don't bother to make sure that the output is good enough.
In my current job we use Goa [2] and its DSL to define the interface of the service. While the OAS it generates is not nearly as elegant as something that you could produce by hand, we've found it good enough to be viable as an artefact we immediately hand over to potential consumers of the service. We've had a lot of success working this way; consumers were able to use their own tooling to stand up mock servers to build against while we worked on our implementation.
The class of tools that generate OAS from code by attempting to map controllers or routes to operations and paths never work well.
[1] https://developer.squareup.com/blog/making-openapi-swagger-b... [2] https://goa.design/
This was made worse through the need to specify the number of people who are travelling to a specific floor so the algorithm can allocate enough space in each elevator. Large groups often ignored this so you’d often find that an elevator you’ve waited minutes for is full, and start the dance all over again.
This is going to be the big struggle for teams who formed in person but are now hiring remote.
I joined my current company about six months prior to the pandemic and had ample time to get to know my colleagues face-to-face, making the transition to remote working very pleasant. I'm not sure if the experience has been the same for people we've onboarded remotely; they're productive but I'm unsure if it'll be easy for them to build up the same kinds of relationships.
You also tend to get into situations where there's a social divide between a subset of the team who have constantly worked together synchronously in the past and new starters who only appear in 2D on Zoom. This may not be a problem for some people, but it's a concern for someone like me who gets a lot of their daily social interactions via work.
This is pretty important and seems to get overlooked.
If you're trying to kick off an initiative that benefits customers, but not in a manner that can be quantified to business stakeholders (one we've struggled with is getting management support to build tools that improve API documentation for customers who develop on our platform), reaching out directly is a useful way to gauge the landscape and come back with a better understanding of who your target customers are and what they struggle with.
That's evidence from the horses mouth that you can take to management to get sponsorship for your project.
Even though most of the indexing and intellisense features are done within the language server itself, there'd still be significant overhead in JSON parsing and serialisation right?
The response example for the `textDocument/definition` request [0] shows a very large snippet of JSON considering the information it conveys:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"uri": "file:///p%3A/mseng/VSCode/Playgrounds/cpp/provide.cpp",
"range": {
"start": {
"line": 0,
"character": 4
},
"end": {
"line": 0,
"character": 11
}
}
}
}
Microsoft used to maintain a log inspector [1] which you could use to see the chatter between the server and client, and there was a _lot_ of chatter with a _lot_ of JSON.
[0] https://microsoft.github.io/language-server-protocol/overvie...
[1] https://github.com/microsoft/language-server-protocol-inspec...
I recently replaced the 1080p display panel on my T490 with a 2560x1440 model with no issues whatsoever.
I've recently started learning C++ and have had to grapple with the complexities of CMake. I'm only a few pages into the paper but it's already done a great job at distilling the problem domain and the core components of a build system.
I also found the beginning to be a great introduction to `make` and the build dependency tree.
I feel _so_ much better after a walk; I have better concentration and increased motivation to tackle difficult problems. Even if I'm having a particularly busy day or with a deadline coming up, I'd rather sacrifice some personal time after hours than my walks.
It’s 100% worth learning though. Tmux is available almost everywhere and it’s an easy way to increase your productivity!
On top of adopting a different mindset when writing docs (you'll need to phrase concepts and provide examples to cater for users who probably don't share the same intimate knowledge you have of the codebase), there's a high cost associated with upkeep. Ensuring that your docs always align with the implementation might be straightforward for smaller applications, but as your API surface grows so will the cracks that outdated documentation will slip through.
There are a few examples of tools which are designed to lessen the burden (that I know of):
- To generate usage examples from your code, Go has the idea of testable examples (https://blog.golang.org/examples) which get rendered in the documentation but are declared as normal functions. These can be easily unit tested.
- To provide usage examples in code without resorting to unit tests, Clojure has `comment` forms (https://clojuredocs.org/clojure.core/comment) which are normal expressions but ignored by the compiler. You can define arbitrary expressions within a comment form (e.g. to execute another function), so these can be used to define usage examples and placed next to the functions they call.
Once you start thinking in terms of requests, responses, parameters, schemas etc the rest should easily fall into place! You also get the benefit of having a machine readable definition of your API if you write your design with the spec.
The gestural interface and limited toolset made it easy to focus on taking notes and arranging thoughts rather than "fighting the program" and wasting time choosing between dozens of pens and colours.
Best of luck with the launch!
I know some airlines supply an iPad which can be mounted to the back of the headrest and needs to be stowed at takeoff or landing. I wonder what kind of testing would be required for those setups.
The current ones from Panasonic seem to have caught up to the original iPad: https://www.panasonic.aero/our-offerings/systems/x-series-bl...
Fructure is an example which looked promising! https://www.youtube.com/watch?v=CnbVCNIh1NA
https://www.amazon.com.au/Working-Public-Making-Maintenance-...
But being the _only_ distribution channel? Probably not the best!
It’s robust software that does was it says on the box. I was initially reluctant to move out of my local vault but the online service has been impeccable.
There's the k8s manifest, Cloudbuild config, various operators for databases, a CloudFormation repo for AWS resources, another one for Datadog config etc. It all feels very disjointed.
> The method finder will take the input objects (receiver and arguments) and perform their permutation to be able to find more results. Then, it will lookup in the receiver's hierarchy the approved and forbidden methods to run on the hierarchy and run them on the permutation of objects.
which sounds like an exhaustive search.
I dug a little further and found this [2] which points to the actual implementation in the `MethodFinder` class. I don't know enough Smalltalk to decipher it :(
[1] https://github.com/pharo-open-documentation/pharo-wiki/issue...
[2] https://csharp.developreference.com/article/18692966/How+doe...