unity-design team mailing list archive

[Kevin Wright <kevin.wright@xxxxxxxxxxxxx>]

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