Here Comes the Documentation

System documentation is not something that I tend to spend a great deal of time on. This doesn't mean that I don't have any documentation and I most certainly do not ascribe to a "the documentation is the code!" mentality. As crazy as it may sound, the vast majority of the documentation for my projects, be it 10Centuries or something else, is found in one of the many A5-sized, graph-ruled notebooks. It's in these notebooks that ideas are first described, (literally) sketched, and refined before being transformed into code. Whenever I have one of those "what the heck was I thinking?" moments, I can grab a physical book, flip to the appropriate pages, and get an idea of where my head was at that day.

Unfortunately this doesn't help anyone else who might actually want to use the tools that I create, which was driven home this past weekend when asked me when there might be some sort of resource that he could look at to get his workflows ready for the upcoming switch from the 10C v4 API to the v5 API. Today the first iteration of a public documentation site goes live.

The New Documentation Site

As with just about every first iteration I release, there will be some blank pages and incomplete placeholders. People will wonder why the Contact form is fully operational while something a little more important like the glossary is incomplete1. Some might take a look at the documentation from a phone and see that things are not aligned quite right. Others will find grammar and/or spelling errors and decide the whole thing is untrustworthy. As the person who designed the website in a couple of hours, then wrote the documentation, I accept any critiques that might be levelled at the work. That said, more of the site will be filled out this week as we get closer to the switch from v4 to v5.

So what sort of things are ready on the documentation site?

  1. the Authentication API
  2. the Terms of Use page
  3. the Contact form

That's about it for today. Tomorrow I'll aim to get the Account, Files, Posts, and Search APIs written and published. If there's still time after that, Bookmark and Locker would be good utilities to document, as these could branch out into their own services given the right use cases. So long as the day job does not require more than 9 hours per day this week, it should be feasible to have the first complete set of documentation ready before April … which would be a solid start to encouraging more people to try v5.

  1. This is simple: the Contact form is already built into the API. All I had to do was wire up some of the HTML to make it work. Everything else needed to be researched, written, and/or modified from the (now retired) v4 documentation site.