2013-04-27/28 - Microcosm Alpha Hack Weekend

^^ it sounds to me as if number 2 is a good pragmatic middle ground. To have all choices as totally independent resources is a little bit unrepresentative of the relationship that they have to each other: they don't really exist independently in the same way that generic collection items do, they exist as a corollary to their sibling choices.

I vote 2.

Shouldn't we be using the official poll API to make these decisions?

Lols

On a less obvious-troll-is-obvious note, the documentation page looks awesome. It's all way over my head, but nice to see such a clear and minimal interface, hopefully it is possible to maintain this all the way through to the finished product!

Well I'm still writing the docs, and we have no intent to have more than 1 page of them.

At least then you could download them by saving the web page, or just use the browser CTRL+F search.

I hate sprawling docs on hundreds of pages when you can't find shit because there's no consistency or sense in how it's all laid out.

sprawling docs on hundreds of pages

wikidocs

Would it make sense to make (some of) the test suite available publicly too, as documentation of implementation decisions? Particularly if you do use something human readable like cucumber?

You think Cucumber is readable?

And yes, I have a test suite implemented using api-easy.

But... these are NOT unit tests, they are integration tests. They manage resources, and as such they modify state in the Microcosm platform.

They are not a good contender to be opened up, as just because the suite passes for me... knowing the state, and having the right auth... does not mean the suite is supposed to pass OK in 3 months time when the state changes dramatically.

So the question I have instead is... what do you need to see that isn't covered by the docs already?

The docs are pretty comprehensive, I've even described why things are as the way they are within the conventions bit. And I do intend to keep them bang up to date as well as comprehensive. And as they're open-source, you'll see changes over time too.

The docs are very low level so that someone implementing against the API can see precisely the data to send and what they should expect to receive. I've not even been tempted to truncate or summarise the example JSON responses as I know as a dev that I want to see what to expect and not just a bit of what to expect. The docs are, for me, the real test suite... to my mind, it should be possible to read the docs, build a client, and for it to work... even without having prior access to the API. Sure that's a bit out there... but all the info is there.

Hmm... though we could provide a dev.microcosm.app site that we wiped daily for such testing.

Though I'd still like to know why you'd need one.

Can you point me towards example of test suites for any other APIs that are the kind of thing you want to see, and describe which bits are useful to you?

Well I'm still writing the docs, and we have no intent to have more than 1 page of them.

At least then you could download them by saving the web page, or just use the browser CTRL+F search.

I hate sprawling docs on hundreds of pages when you can't find shit because there's no consistency or sense in how it's all laid out.

Ah, sorry I didn't mean keep all the words, as I said, its all over my head. I just hope you keep it pretty!!!

I'm afraid that I only have historical anecdotes rather than live examples. Sorry.

My observances over the last ten years of working in software with automated test suites is that broken tests get fixed quicker than broken docs.

Having said that ^ I gave realised that we may be talking at cross purposes.

I meant giving people a view of test cases rather than be able to run tests.

It can be useful for devs to see your cases such as:

Given: some slightly odd state
When: I send the API something a bit edge case
Then: do this particular thing.

It can be useful for devs to see your cases such as:

Given: some slightly odd state
When: I send the API something a bit edge case
Then: do this particular thing.

Now that makes sense.

I certainly do want to document common use-cases.

Events are a fine example of something that can have non-intuitive handling of state. The is business logic about events, how they move from 'proposed' to 'confirmed' and eventually are either 'postponed' or 'cancelled' or they become past events that have happened.

When I'm done with the basic documentation and a basic and complete API, then I'll move to advanced functionality and documentation.

Right now I'm spending more time documenting than coding, and that's a worry as we're probably a little bit behind where we want to be.

My observances over the last ten years of working in software with automated test suites is that broken tests get fixed quicker than broken docs.

I shouldn't worry, I'm not a big believer in fixing broken tests for the hell of it, but I am a big believer that documentation describes intent better than tests do and that the code should match the documentation and vice versa.

Now, I realise some devs will scream at what I've just said, but let me phrase it a different way...

What does every software bug that has ever existed got in common?

They all compiled, passed the type checker, were syntactically correct, passed the unit tests, and the integration tests, and the quality assurance.

Every bug, passed every test.

And once you deeply appreciate that, you have to concede that tests are only as good as the anticipation of every scenario, and that bugs will get through regardless. Far more important than being pedantic about creating swathes of tests is good documentation of what should happen, and the ability for deviance from that documentation to be treated as a bug of high importance. Either the docs are then wrong, or the code is. And in the case of an API with developers implementing against the documentation and provided interface, having their action be the test that needs to pass is critically important.

It effectively declares that the documentation is the spec, and the implementations are the tests, and that if the code doesn't work that we either have a bug in the code or a bug in the spec.

So whilst I have tests to act as an insurance policy against us breaking our contractual interfaces (the REST API)... I much prefer working to documentation and developer feedback for the raising and resolution of bugs.

This is far more like behaviour driven development rather than test driven.

My observances over the last ten years of working in software with automated test suites is that broken tests get fixed quicker than broken docs.

A good side effect of having the Django project open-source is that all the tests (frontend Selenium and Python tests) will be visible, and as the API changes they'll all have to be updated (as it's what we'll use for the main microcosm web client).

This'll be well documented and readable so even if someone doesn't know any Python/Django specifically they can still get a good picture of what's going on.

I realise that isn't the same as having an API test suite of course, but it will at least demonstrate how a real client uses the API on top of documentation.

Good stuff all round :-)

I must say, I thought the new Microcosm theme worked very well. Sad to see it go.

Impressed that you've progressed it to the point where you'd already test it on here

;)

There's a theme?

At the moment... today... it looks worse than Craiglist.

Updated first post...

We'll open up the office on Saturday and Sunday from 9am through to 9pm.

We're currently looking to get a beer fridge, and wondering what you guys want to drink... lighter stuff like San Miguel seems on the cards, just not Carling or something.

We'll probably order things like pizzas as and when people suggest they're hungry or roughly just after noon and again around 6pm.

Anyhow, who's in?

1. Velocio
   
2. blueprints
   3....
   

not sure if there will be much for me to do.
Could def pop by Sat arvo and say hi! :)

Hah, do that. Have a beer too :)

This is just a wider question regarding money actually and how the company accounts are looking and whether the initial funding stage will get you to where you need/want to be and if not how re-financing will look take place.

Did you get the investor update? I supplied it to Seedrs, whom I believed would be distributing it to all of the investors.

Nope.

goes to poke at his emails I don't seem to have one either :(