Protobuf Docs

[Yuffster]

I ended up producing some documentation byproducts as part of my work at @mapbox/osm-data-platform, specifically on the format of OSMPBF files.

A lot of the documentation digs into ProtocolBuffers at the bit level; with various illustrations. It's meant to be a companion to the official Google docs.

Some of it is specific to the way OSM stores its data, but perhaps some of this could be useful for your documentation, either integrated or as a link?

https://github.com/mapbox/osmpbf-tutorial/blob/master/Planetfiles.md

/cc @mapbox/core-tech

[springmeyer]

Nice tutorial @Yuffster. The protozero tutorial could link to this doc as an another example of getting to know protocol buffers (in https://github.com/mapbox/protozero/blob/master/doc/tutorial.md#getting-to-know-protocol-buffers).

[joto]

Nice writeup @Yuffster. Please link to it from https://wiki.openstreetmap.org/wiki/PBF_Format where people interested in the OSM PBF format will look.

I am sceptical about using this as an example for how Protocol Buffers work. The OSM PBF format is so much more than Google Protocol Buffers and it has been confusing for people again and again that we are using the same name ("PBF") for both. If somebody is new to the whole Protocol Buffers thing, maybe needs it for vector tiles, burdening them with the whole OSM stuff make it more difficult for them. Especially the double level of Protocol Buffer encoding in OSM PBF files is confusing as hell at first. That being said, I don't mind linking to it from the protozero docs if it comes with a warning. :-)

[Yuffster]

Yeah, I had the same concern with the mixing of the docs. It's hard enough to learn one thing without learning an unrelated thing and trying to figure out where Protocol Buffers ends and OSMPBF begins.

It wouldn't be hard to toss together a quick illustrated run-through of some simple PBF Messages now that I have the Illustrator templates and diagraming code, though. 🤔

[joto]

No movement here for a while, closing this. If anybody wants to write more documentation for Protozero, that's of course welcome.