std.serialization: pre-voting review / discussion

[Tobias Pankrath]

On 08/12/2013 03:27 PM, Dicebot wrote:
> Stepping up to act as a Review Manager for Jacob Carlborg std.serialization
>
> ---- Input ----
>
> Code: https://github.com/jacob-carlborg/phobos/tree/serialization
>
> Documentation:
> https://dl.dropboxusercontent.com/u/18386187/docs/std.serialization/index.html
>

I had no look at the code, but just opened the documentation, asking the 
question: "What do I need to do to serialize this graph data structure, 
I have here?". The documentation does not seem to give a straight answer.

Now, that's an issue I have with almost all phobos modules, for example 
with std.container, but I'll raise this point here: Our documentational 
standards are not good enough, because all we ever have is some API 
documentation ala this is module X, it contains the symbols A, B, C, 
which have a short description respectively.

However a good documentation (look at docs.python.org for example) needs 
to do more. The module has a purpose, because it should help me to 
accomplish a task. The documentation must say (preferably in a single 
location) what this task is and how this module/library may
help me in accomplishing it's task. An outline of the basic design 
decisions (for example where does std.container mention it's structures
have reference semantics?) are often invaluable in unterstanding api/
more detailed documentation.

I know how much work such documentation is and I surely wouldn't vote 
against std.serialization just because of this. But it's one of the two 
biggest hindrances if you want to get started / productive with D. (IMHO)