RSS Feed

Personal Gains from Writing Documentation

March 28, 2018

Developers hate documentation. They hate writing it, and they hate reading it. Good code is self-documenting - right? Well, yes - to a certain degree. The trick is not what you know, but what you know exists.

 

I have always loved factoring my common code out into libraries. In 1980 this was in FORTRAN, today it is C# for Unity3D. And each time I fall into the same trap. I get immersed in the creation and expect I will remember how to use it next time.

 

When reading a blog post from Jason Weimann of https://unity3d.college, I decided on taking his suggestion of publishing some of my work on the Unity3D Asset Store (https://assetstore.unity.com).

 

Because I don't do things by halves, this involves examples and the dreaded documentation. Writing the tests helped me find holes in my design while writing the documentation highlighted how much I forget about the functionality.

 

Only minimal documentation is needed when writing for libraries that are called by code. A developer needs to know that the functionality exists and examples on how to use it. When dealing with a complex framework such as Unity3D, we need more information. How does the code work with game objects, components and assets? How can I use it to solve my problem?

 

Too much documentation is as bad as too little. Examples again provide the best way to fill out details.

 

As a teaser to my work, here is the documentation for a few Unity3D UI Components: https://paulmarrington.github.io/Askowl-UI/Assets/Askowl/UI/Documentation/Askowl-UI

 

If you want to read more, go to http://www.askowl.net/unity-packages.

 

 

 

Share on Facebook
Share on Twitter
Please reload

Featured Posts

My limited tests show that Dictionary is faster than `SortedList`. The latter uses `Array.BinarySearch` to find entries. I have read other performance...

How are C# Dictionaries so Fast?

August 27, 2018

1/5
Please reload

Recent Posts

April 12, 2018

Please reload

Archive
Please reload

Search By Tags
Please reload

Follow Us
  • Facebook Basic Square