Jump to content
  • entries
    940
  • comments
    5,894
  • views
    863,943

Coders Gonna Code, Haters Gonna Hate


Josh

4,077 views

 Share

Lately I've been talking a lot about making non-programmers happy, so here's something for the coders. B)

 

For Leadwerks3D documentation, I considered three possibilities:

-IPB-based docs

-Wiki

-Offline CHM files

 

Each has their own strengths and weaknesses, as always seems to be the case.

 

IPB

A bit slower, harder to organize, harder to edit, looks really good and consistent with the site, search requires quite a few clicks to get where you want to go, missing table of contents is a bummer for long pages.

 

Wiki

A target for spam, doesn't match the main website, user-written docs cause fragmention and a mix of official and unnofficlal information, nice table of contents, good searchability.

 

Offline CHM

Fast, doesn't require internet connection, easy to edit, Windows-only.

 

I dismissed offline docs simply because we wouldn't be able to post a link to refer people to a certain page. I decided on a wiki because of the better search functionality, table of contents, and ease of editing.

 

Here's what I have in mind for the docs. Because Leadwerks3D is written in C++, we're able to document members, constructors, operators, and other stuff we haven't had access to in the past. Best of all, almost everything works exactly the same in Lua, including function and operator overloading. :D

http://www.leadwerks.com/newwiki/index.php?title=Vec3

 

I'm also a big fan of the ease with which we can add internal links. For example, the Vec3 members in the AABB class documentation link straight to the Vec3 class page:

http://www.leadwerks.com/newwiki/index.php?title=AABB#Members

 

To avoid spam, and to make sure I can answer any questions about the contents of the wiki, it's going to be read-only. Community tutorials have been very useful in the past, and we're going to continue that going forward, either through a subforum or database for Leadwerks3D tutorials.

 

I think having one page per command and an example for every single command has been more redundant and time-consuming that we have needed. I want to list the syntax for each command only once, like this:

http://www.leadwerks.com/newwiki/index.php?title=Entity#SetPosition

 

Instead of making a lot of redundant examples (Do we really need a page of code for Entity::SetPosition() AND Entity::SetRotation()?) I hope to provide more comprehensive examples showing how to actually do something, and how the functions can be used together to do interesting things.

 

In general, I want to go into much more depth with the Leadwerks3D documentation, on all aspects of using the program, because I plan for this iteration of our technology to have a pretty long life. If you have any suggestions, just let me know.

 Share

13 Comments


Recommended Comments

Instead of chm files, why not just plain html files that open in any browser on any platform? You don't need to have them on HTTP servers if the contents don't change.

 

It counted as a "manual" as far as Quake 3 was concerned, and that was the first time I really saw it done.

Link to comment

Instead of chm files, why not just plain html files that open in any browser on any platform? You don't need to have them on HTTP servers if the contents don't change.It counted as a "manual" as far as Quake 3 was concerned, and that was the first time I really saw it done.

Wikis are much easier to edit. The table of contents is handled automatically, and internal links can be added just by surrounding a work with [[brackets]]. It probably would take three times longer to edit all that HTML, and every change would be painful. Plus, people want to be able to search them and not everyone will think to use Windows search (I think they messed it up in recent versions, too...one more reason I prefer XP. :blink: ).

 

Is there any way that members only could add to a wiki?

I would have to create all accounts manually. Apparently there was at one time a bridge for IPB and MediaWiki, but I am not sure if it works. Then there is the issue that I have to be able to answer all questions about these docs, and if it's something a user added, I might not be up to date on that knowledge.

Link to comment

I would strongly suggest keeping the 5 or 10-line examples (those that don't overlap, at least). It's very valuable to have quick function information at my fingertips and to not have to wade through dozens of lines of unrelated code and documentation just to (hopefully) find and understand how a function is used. The more information that's presented, the more likely it is to not be understood.

 

That said, I'm sure I and others will find the comprehensive examples informative and helpful as well.

Link to comment

That makes sense to me. It's kind of silly to have a full page of code just to demonstrate Entity::SetMaterial or something like that. If you look at the Vec3 operators, I made small examples that aren't entire self-contained programs. Sometimes I need to stop being so pedantic about everything.

Link to comment

..im seconding what gamecreator said..few lines of example code with each parameter description is way to go..also, i hope that under 'programmers' expression, you primarly thinking on people whos using raw C++, C# and Bmax, rather than scripting language..having said that, i also hope that system will be fully available in fashion as current LE is, because to me personally, none of future editors has any value , because from my experience i have so far, most of tasks i needed to perform, and requests from artists, were way way beyond offered toolset capabilities (not just LE, but Phyre library as well) , so i would like to be able to build my own tools from scratch for certain targets .. i really hope for this things because im planing to use LE 3 fully on mobile devices + mac .. if not..then..ill have to say good bye..

Link to comment
i also hope that system will be fully available in fashion as current LE is

Yes, don't let my positioning of it as a "visual game design tool" scare you. You've still got an API-oriented engine under the design layer. I'm just adding a layer of control designed for people who don't want to program. Who knows, you might even find it useful for some tasks.

 

i hope that under 'programmers' expression, you primarly thinking on people whos using raw C++, C# and Bmax, rather than scripting language

I think C++ is the best language to document things in, because it is a standard everyone can follow along. I can't really write syntax descriptions in Lua since all variables have no type. It's easier to convert a C++ examples into C# or Blitz or Lua than it is to go from another language to C++.

Link to comment

Consider many users now use ipads and such for reading, the best way to do it would be an xml /database based documentation being exported to html (with a download full html documentation link) and pdf. There are a number of tools to do that we use in our company if you need help on that.

 

As long as tutorials go I really love the style of this book

Essential C++

 

also introduced with some examples here

http://www.entish.org/realquickcpp/realquickcpp.html

 

After reading several C++ books (I come from C#) I really like the approach, it gives a full tutorial with cleverly thought of in depth examples for real world cases.

Link to comment

I also agree with GameCreator. Short examples for all functions. You'll be able to use the same example for a bunch of different functions in some cases

Link to comment

I agree with Game Creator as well, some concise examples demonstrating all the parameters of a specific command without all the initialization fluff that is cluttering some now. Personally I don't really care in what shape or form we will eventually have them, as long as they're thorough and complete.

Link to comment
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...