Home

TL;DR ... No one reads the documentation

I'm just being honest. There's just too much documentation for VDMJ. No one is going to read it.

Yeah, I get that. But we have to have some written documentation, otherwise all we have is code and that's a tough way to understand any large system. The comments in the code are... 'thin'. Besides, regular users won't want to read code.

Sure. But there's still a mountain of this stuff. No one knows where to begin!

Well, I could write some sort of "Overview" maybe, like a meta-doc?

Ugh, that's even worse. It just adds even more documentation.

Yeah okay, but what else can I do?

It's best if you explain to people personally.

Oh right, and how am I supposed to find time to do that?

Hmmm, even if you recorded some sort of presentation, no one would sit through the whole thing

Hey, are you saying I give boring presentations?

LOL, yeah. Well okay no, not really, but a recorded presentation would still be way too long. People need a short punchy way to get into the system.

Like what?

Well... I don't know! But when you explain things to people one-to-one, it's really good.

But that's because I can ask what they need to know and then send them to the right places, and explain the basic idea for them first.

Right! That's it. It's good when you explain the basic idea for people, then let them dig into the detail at their own pace.

Okay, but I'm still not seeing how this helps with documentation.

How about if you explain it to me?

What?

I mean, why don't you explain to me what the documents are for and how to use them?

Yeah... still not seeing how this helps?

Well then, after you've explained something, we can write up that explanation in the wiki

And that helps because... how?

Because if you have a conversation with me about what's in the docs, that's roughly the same conversation you would have with anyone, once we've decided what the person wants to understand.

Ah, so if they read that...

Yeah, if they read that, it's like them talking to you about it. Well, sort of. It's worth a try. It's got to be better than staring at a mountain of documents and not knowing where to start.

Okay, it's worth a try. And you'll write it up on the wiki? Because I'm thinking that could be as much work as the documents themselves.

Promise.

Right, so where do you want to start?

How about we start with something simple, like you explaining what VDM is all about?

And you'll write that up?

Yes. In fact I'll put it here