In my ‘hey I’ll just post something real quick’ haste this morning I left out a couple of important points that I should clarify:

Context Is Important

1. I’m working on writing new API and creating an application framework.
2. I’m not trying to sell a concept. DDD was just a title, I’m not trying to convince you to work this way. If you want to, great. If you don’t, awesome. If you want to marry a horse, I really don’t care.
3. I’m talking about starting with tutorials for end users, not API docs or design docs.

So what’s the point?

Doc first or you might not doc at all.

Reading about test first development one concept that stood out to me was “if you don’t write the tests first, they probably won’t get written”. I think the same thing often happens with docs. If you leave the write the tutorial action item laying around there’s a good chance it will never happen.

So write your docs right now.

Tutorials put you in someone elses shoes

A lot of people have pointed me to Behavior Driven Development. Looking over some BDD examples it feels like BDD docs are more about “what this should do” than “how you should use it”.

Writing tutorials first puts you in the users shoes. It makes you think about how they are going to use your app/library/api and I think having this different perspective will improve your useability.

So try to think of things from a users point of view.

Docs are just as important as tests

This statement probably pisses you off. But a wise man once said: If a feature isn’t documented, it doesn’t exist. — wise man I believe this is true. You can have the greatest most bug free code coveraged app in the history of the world, but if people can’t use it, who cares?

Features only matter if they’re used.

So there you have it

A lot of software nowadays has a terrible disease know as i-will-write-the-docs-later-itis. Some projects have an even worse disease the-community-will-provide-docs-itis. Eek.

I’m trying to avoid these diseases because I want people to use my software and I want the experience to be enjoyable. The stuff I’m writing is open source, but I’d prefer if people didn’t have to look at the source to find out why the fucking property can’t be updated from a fucking callback or things of that nature.

Anyways, hope that gives everyone a better idea of what I’m trying to do.