Jump to content

Editor Documentation

JMK

1,631 views

I got the editor documentation written pretty quickly. It was hard to start, but once I figured out how I wanted to lay out the information, it all started flowing pretty easily.

 

Documentation in Leadwerks Engine 2 was a weakness, especially in stuff other than the programming reference. This is unfortunate, because I have come to see documentation as the final product. Everything in the development cycle leads up to the ability to write good documentation.

 

Good documentation starts with good program design. It would have been difficult to give the same attention to detail in Leadwerks Engine 2 as I am now, because there was much more behavior that was undefined, or left up to the user. Because Leadwerks 3 absorbs a lot of that complexity, I can definitively say "if you want to do X, press this button". It makes for documentation that is nice to read, and kind of fun to write.

 

Here's a screenshot, just to give you an idea of the formatting and style I am using.

blogentry-1-0-17722600-1358234211_thumb.jpg

 

I usually feel overwhelmed by the documentation when I look at game engines. It's hard to know where to start, and I just feel like I am picking up random bits of disorganized information. I am hoping the manner in which I have organized our docs will provide a streamlined learning experience, with the ability to drill down to more detail when needed. My organization is as follows:

 

Editor

This covers the entire Leadwerks workflow and art pipeline. You can find answers to all non-programming questions here.

 

Script Reference

This section describes all the object scripts included with Leadwerks, and how to use them to make game interaction.

 

Programming

This section discusses general information about programming with Leadwerks, in C++ and Lua.

 

Command Reference

This section provides detailed descriptions and examples for the entire Leadwerks API.

 

Index

This is a list of all pages in the documentation, in alphabetical order.

 

It feels very easy to navigate and it doesn't take long to learn how the entire workflow and art pipeline work, but it's not lightweight by any means. The docs have more than 600 pages! Most of that is for individual class functions, which is information you will usually specifically seek out, rather than just reading through them all for fun.

 

--EDIT--

I added some additional fields for C++ and Lua examples, with a tabbed interface to view each:

blogentry-1-0-86149100-1358312135_thumb.png



12 Comments


Recommended Comments

I know that feeling you described concerning the usual documentations. Your documentation seems to be easy to understand, and it has structure. I also like the idea of "in case you want to ... then do ...", it feels complete

 

thank you for doing all this

Share this comment


Link to comment

Will the documentation be in offline searchable format, like chm?

The docs are online only. Mac and Windows have completely different help systems. I'm not even sure if Windows still supports CHM without any fiddling. I'm looking into having a printed manual produced, in addition to the online docs.

 

I know that feeling you described concerning the usual documentations. Your documentation seems to be easy to understand, and it has structure. I also like the idea of "in case you want to ... then do ...", it feels complete

 

thank you for doing all this

It's something I learned from marketing. You have layers of messages, arranged from simplest to most complex. So you try to communicate the big ideas first, and then drill down to more detail.

Share this comment


Link to comment

I'm looking into having a printed manual produced, in addition to the online docs.

If it can be printed, it can be printed into a PDF file too, that's good enough for offline reading.

Share this comment


Link to comment

Yeah, PDF is actually the format the printer wants, so we have to make it anyways. I don't mind including that.

Share this comment


Link to comment

Heck, it must be good enough, because even huge professional companies like Yamaha deliver their electronic documentations as PDF, they do it for example for their Music Workstations, and I'm quite happy with Foxit Reader: fast browsing and searching, convenient page layouts and zooming, and bookmarks. And the printed books in several languages which come with the Workstations are exactly the same as the PDFs.

Share this comment


Link to comment

Looks good.

I'd like to see the following to make the search as useful as possible by creating references with as many similar terms as possible. One thing I find the hardest to deal with in new programs and/or code libraries, is knowing what I want to do, but not knowing what word(s) to search for to find it.

 

As an example. You're calling them CSG primitives created in the 3D view "brushes", or maybe it's a brush that draws them. Either way, if I was relatively new to the program and/or CSG modeling tools, I wouldn't know this, but I would know what a 3D shape, or a primitive, or a polyhedron was from basic geometry. So..having results come up for multiple keyword searches, is, IMHO a key feature of good documentation. Another good approach is being able to sort things in multiple ways, such as, what it does (physics, rendering, etc.), and alphabetically, and by it's class/code hierarchy if it's code.

 

The second thing I'd ask for is that the API reference have decent descriptions of what things do, what the parameters and returns are, and at least one small code snippet to demonstrate basic use. It drives me bananas when the docs are just some doxygen dump, filled with programmer pseudo descriptions that often just repeat the name of the class or function.

Share this comment


Link to comment

And I'd put my money where my mouth is. I'd help you convert current wiki samples to the LE3 format for a few dozen of the simpler functions, if you needed the help.

Share this comment


Link to comment

Yeah, snippets and simple examples like those on the wiki are VITAL.

See original post.

Share this comment


Link to comment

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Add a comment...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...