← Back to team overview

unity-design team mailing list archive

Re: Make design/testing contribs easier by providing better API docs earlier.

 

On 03/08/2012 03:47 AM, Jo-Erlend Schinstad wrote:
Obviously, in order to create a good design, you have to know to a certain degree where you're going in advance. However, I don't think it's possible to anticipate everything. For a design to really shine, I think it needs to be toyed with and stretched as much and as soon as possible. I think this is particularly important for addons, such as lenses, appindicators and system indicators. Two things might happen; either you prove that the design is sound, or you'll find examples of things that can't be done in the current design. In that case, you'll have hard evidence of things that doesn't work well. Then it must be decided if the design should be altered to accommodate (which is easier when you have actual code to reproduce issues), or if the limitations should be accepted. In any case, I would consider this important data to have as early as possible.

Now, playing with Unity technologies is anything but easy. API docs are scarse and when they exist, it's not easy to know which to use or how to use them. There are some blog entries out there, but since the tools are difficult to learn, there's not many of those either. On developer.ubuntu.com, the newest API docs I can find for using Unity with Python, is http://developer.ubuntu.com/api/ubuntu-11.10/python/Unity-4.0.html.

Does that mean that the API is in version 4.0, or that it is for Unity 4.0? In that case, does it mean it's no longer usable with Unity 5.4? This is one example of things that makes it difficult to learn Unity tools. I don't know if or how much Unity APIs have changed since Unity 4.0. But it sounds like it may be a lot. I find it difficult to motivate myself to learn how to use an API on the odd chance that it might not be completely useless. This means I can't test my wild ideas in practice, which means I can't provide as much feedback as I otherwise would and should.

I would propose, and politely ask, that in the future, when there is a new version of Unity, even if the APIs haven't changed, that they get their versions bumped to be the same as Unity itself. If there are no changes since the last version, then the docs should just say so in the beginning. If there are changes, then they should be highlighted like "Changed since version xx".

This would make it very much easier to navigate the jungle. But if documentation is also written ahead of the implementation, then it also becomes much easier for "outsiders" to help write automated tests, for instance. That might help core developers focus on what they're good at, and is a relatively easy way to contribute useful code to Unity. When Unity is released, we will already have more people who really understands how things work, which means better support for new developers, but also users in general. And, of course, by release, we'll have more addons and cool stuff for users to play with, which helps promote Unity in general.

Does it make sense, and is it something you'll be willing to consider in the future?

Thanks for reading :)


Another good thing about documentation in general is that when an expert (developer, designer, architect or whomever) articulates their vision (e.g. a plan), achievement (e.g. a working API), or guidance (examples and guidelines) it probably means the quality of what they have done is much higher -- because they have given careful thought to their end user.

Design & developer documentation (including API documentation) is an effective channel for expert to expert communication -- people on the one hand who have created something of value and on the other those who are going to use it.

Kevin





References