Flatbuffers: Documentation is terrible

[maticmeznar]

After learning the basics of Protocol Buffers a few months ago from the excellent documentation on Google's website, I decided to try FlatBuffers today. Needless to say, things are VERY POORLY explained, if at all. It really should be done better.

Please look at official Protocol Buffer documentation on how this should be done.

[stewartmiles]

I'm sorry to hear you feel like this. Are there particular areas you feel
need improvement?

On Fri, Sep 18, 2015 at 8:40 AM, maticmeznar [email protected]
wrote:

After learning the basics of Protocol Buffers a few months ago from the
excellent documentation on Google's website, I decided to try FlatBuffers
today. Needless to say, things are VERY POORLY explained, if at all. It
really should be done better.

Please look at official Protocol Buffer documentation on how this should
be done.

—
Reply to this email directly or view it on GitHub
https://github.com/google/flatbuffers/issues/273.

[maticmeznar]

The entire documentation needs to be overhauled and rewritten for a common developer, not an expert. Some of the things that are not well (or not at all) explained are: root_type, vector field accessor, vector, getroot, offset, builder, classes in Go, attribute, enum, union, default values, scalar, non-scalar (why bother a developer with the concept of "scalars" and endinness). There is a huge lack of examples with explanations given line-by-line. There is simply not enough information to understand how to use FlatBuffers properly. Godocs are useless.

[maticmeznar]

I just spent another hour trying to use Flatbuffers in Go and I have nothing but frustration and anger to show for it.

[vijairaj]

@maticmeznar, You might want to have a look at the tests. At least for C++, I found the test cases more useful than the docs.

[rubber-duck]

I agree with maticmeznar - I had to wade trough tests to figure out how stuff works just enough to get something working - still don't understand the logic behind the API.

For example one non-obvious thing is why does vector of tables generate c++ definition as vector> - from what I seen you can iterate using iterators (ie. for(auto it = vector.begin( ) ...) ) but using for(auto& object : vector) will iterate trough offsets and it's not obvious why or how to transform offset to table instance.

[ghost]

You are probably right. And as much as "rewrite it all" would be great, the reality is:

• It is sometimes hard to anticipate every possible question people may have, especially when you don't have those questions yourself. The documentation is best improved through iteration.
• FlatBuffers is an open source project, and some parts of the documentation (e.g. the one for Go) were made by external contributors, not large teams of professional writers at Google. Even the main documentation was written by a single programmer (me). Protobuf has had much more time for its documentation to mature.

That said, the best way to help us (and thus help us help you) is to give us precise examples of questions you don't feel are answered, which allows us to easily go add exactly the material to the documentation. Even better if these are reported as issues on a per-language basis, since different people work on different languages, but feel free to just add them to this issue for now.

I agree additional "step by step" tutorials with more sample code would be great as well, and is something that be great to help from external contributors from. These could either be additions to the main documentation, or articles elsewhere we can point to.

[maticmeznar]

Ok, I came up with the following example:

For the following pseudo JSON, how can someone (in Golang):

• write a schema
• compile a schema
• set each value
• serialize the whole thing into a []byte
• unserialize from []byte
• retrieve each value

{
"email": "[email protected]", // utf8 string
"age": 42, // uint8
"regTs": 1421539200, // uint32
"hobbies": ["sprinting", "board games", "baking"], // array
"alive": true, // bool
"skills": { // map
"golang": 3, // uint8
"linux": 6, // uint8
"itsec": 6 // uint8
},
"authHash": "b3VyZWhnMHI4ZmpzJ2QgZjl3YSB0OTQzdyA5IG9pZg==", // []byte
"balance": -664926102 // int64
}

[ghost]

On Tue, Sep 22, 2015 at 1:05 PM, maticmeznar [email protected]
wrote:

Ok, I came up with the following example:

For the following pseudo JSON, how can someone (in Golang):

• write a schema

This is all in: https://google.github.io/flatbuffers/md__schemas.html
and is not dependent on the language you're using, so the information in it
is not going to be repeated on the Go page. The Go page is purely for Go
specifics not found elsewhere.

If there's anything in that page that needs improving, let me know.

• compile a schema

Similarly, that is here:
https://google.github.io/flatbuffers/md__compiler.html

• set each value

The Go documentation has an example on how to set values in the text from
"You can also construct these buffers in Go.." onwards, which shows
examples for many different data types. The examples correspond to the
example schema in the pages above, so that should hopefully help.

It's very likely that this is not complete however, so let us know if
anything is not answered by it.

• serialize the whole thing into a []byte

This is in the one before last paragraph on the Go page.

• unserialize from []byte

That's what the Go page starts with. I'd agree that starting with
deserialization before serialization is maybe a bit odd, but starting with
how to read FlatBuffer data somehow made sense.

• retrieve each value

Also at the start. Should probably show access to more kinds of values.

-

{
"email": "[email protected]", // utf8 string
"age": 42, // uint8
"regTs": 1421539200, // uint32
"hobbies": ["sprinting", "board games", "baking"], // array
"alive": true, // bool
"skills": { // map
"golang": 3, // uint8
"linux": 6, // uint8
"itsec": 6 // uint8
},
"authHash": "b3VyZWhnMHI4ZmpzJ2QgZjl3YSB0OTQzdyA5IG9pZg==", // []byte
"balance": -664926102 // int64
}

Most of these are in the example.

The Go documentation is lacking an example of a vector of strings or
tables, it only shows a vector of bytes.. that would be good to improve.

Wouter

[hash-X]

@aardappel , If you don't mind ,I am glad to write some document about java example in FlatBuffer. Because in most China technical forum I see. The example about java I have seldom to see. I can not see any example about Java used in Flatbuffer in our major technical forum (51cto, CSDN) . But I think I am good at java used in FlatBuffer and I can write more detail example in java used in FlatBuffer. But I don't know how to do next. From where to write these document ?

[aardappel]

hash-X: go ahead :)

[ghost]

We just pushed an overhauled version of the documentation that includes a tutorial shared by all languages:
https://google.github.io/flatbuffers/flatbuffers_guide_tutorial.html

This tutorial plugs a few holes, and should make it easier to improve the documentation and keep all languages in sync. The language specific pages are now just to give language specific tips, build instructions etc.

Those who wanted to contribute to the documentation can now do so based on this new structure.

[ghost]

I will close this particular issue, please open new issues for more specific documentation problems as you find them.

[rw]

Excellent!

On Tue, Jan 19, 2016 at 3:51 PM, Wouter van Oortmerssen <
[email protected]> wrote:

I will close this particular issue, please open new issues for more
specific documentation problems as you find them.

—
Reply to this email directly or view it on GitHub
https://github.com/google/flatbuffers/issues/273#issuecomment-173026740.

Robert Winslow
@robert_winslow http://twitter.com/robert_winslow