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!

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

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

Yeah okay, but what else can I do?

It's best if you explain things to people personally.

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

I'm just saying it's better when you explain it. But 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 find out what they need to read.

Like what?

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 that would help?

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 each document, that's roughly the same conversation you would have with anyone, once you've decided what the person needs to understand.

Ah, so if they read that ...

Yeah, 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 that could be as much work as writing the documents themselves.

Promise.

They'll still need to be able to easily find the conversations about the different documents though?

Sure, but I can create a table of conversations on the wiki. So people can see what's there and jump around easily.

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