Official documentation

[Josh]

Check this out:

http://leadwerks.com/werkspace/index.php?/page/databases/docs?category=8

 

The language box doesn't do anything right now, and the top-level template isn't written.

 

I am getting pretty comfortable with database templates. Do you have any suggestions for features I should include? What is your dream documentation system like?

[Canardia]

It's pretty cool, and feels more like a real program than a web page.

You should include syntax highlighting, a screenshot field, and also a file field where one can put supplementary files for the example.

And you should make it possible to add a new language.

[Guest Red Ocktober]

why is BlitzMAX at the bottom of the selection list !!? (just kidding)

 

seriously... this looks good...

 

 

hey... please don't take down the old tutorials... they're still quite informative and still being used...

 

thx

 

--Mike

[Roland]

Yes. Looks very nice and Pro

[Cornell Cook]

Looks really good, can't wait for it to be fleshed out.

[Pancakes]

I said so in the little update shout box thing. Hire Aggror. His docs are amazing. Really professional and also they work even on noobs like me. What more can you ask for?

[Josh]

Aggror still needs a system to fill the data into.

 

I am most interested in hearing what features you want to make the docs system really useful. We can do pretty much anything, so speak up now.

[Canardia]

You could also auto-generate VS2008 and VS2010 project files, like the NeHe OpenGL tutorials have, although those are hard files, and not auto-generated.

And if you wanna go even further on user experience, you could generate the whole example as an exe (rar self-extract autolaunch exe), so the user can just click on the exe, choose save or run and the example will run.

Then you could also have the server generate a video of the example, but those could be of course generated when the example has changed only, so there's no need to generate them each time. Well the same goes for the exe too.

 

Then you could have all keywords as links, so if one example mentions "CreateCube()" it would link to the CreateCube doc example page.

 

Then you could have the doc system generate a .chm help file, which is automatically updated when any doc page changes. You could also have it generate a HTML version for the offline help file.

[Josh]

There are two ways I can set it up:

 

1. You enter syntax for C++, Lua, etc., and a dropdown box chooses the language, and everything is displayed in a consistent format.

 

2. I make the page editing pretty much like the wiki.

 

If I use choice number 1, it's great for command documentation, but useless for general documentation that isn't in a specific format. If I go with option two, it's more flexible and you can write an article about using the editor or something, but it isn't doesn't let you switch languages.

 

Perhaps these docs should be used for commands only, and a separate tutorials/articles system should be used for more tutorial-style information?

[AggrorJorn]

That looks good. Out the top of my head:

• Syntax highlighting per Language.
  
• Adding small images or screenshots
  
• Video Support in swf or flv (or just youtube and vimeo)
  

 

The main page should guide the user to his desired language or not language related tutorials.

[Canardia]

Well you can just have a generic language, which doesn't auto-format anything. I would try to keep as much of the functionality as possible under one system.

[AggrorJorn]

The way the frontpage of Leadwerks is done now should also be used for the tutorials and commands. Small thumnbnails for various sections.

[Josh]

The way the frontpage of Leadwerks is done now should also be used for the tutorials and commands.

Can you elaborate on that more?

[macklebee]

why is the spacing in the example doc so large? kinda annoying that 15 lines of code take up a page and half and requires you to scroll down..

 

so is your goal to replace the wiki? will adding pics and vids to this documentation system actually be deducted from a person's total global upload quota?

[AggrorJorn]

Many websites have small thumbnails or large icons for special sections and categories. The frontpage already uses this to keypoint several engine techniques and capabalities.

We could use the thumbnail technique to create categories for programming and tutorials.

 

 

 

another suggestion:

- Adding options to download commands or tutorials directly to pdf.

[Josh]

why is the spacing in the example doc so large? kinda annoying that 15 lines of code take up a page and half and requires you to scroll down..

The parser is presently adding line breaks into the code text.

[Canardia]

I don't think PositionEntity will produce a picture of a cat:

http://leadwerks.com/werkspace/index.php?/page/databases/docs?record=1

[macklebee]

I don't think PositionEntity will produce a picture of a cat:

http://leadwerks.com/werkspace/index.php?/page/databases/docs?record=1

 

thats an undocumented feature. what? you didn't know about that?

[omid3098]

I'm highly agree with Aggror about thumbnails and more visual guide lines..

[Josh]

I am leaning towards using three databases:

 

The reference database contains the engine command set. Each record entered has info for C++, C, Lua, etc. To change the info displayed a php variable will be included in the url, i.e.:

http://www.leadwerks.com/index.php?/docs/commands〈=cpp

http://www.leadwerks.com/index.php?/docs/commands〈=bmx

http://www.leadwerks.com/index.php?/docs/commands〈=lua

 

The database display will choose which syntax and examples to display based on the language setting. The combobox can be used to change the language.

 

 

The second database is official documentation. This will be separated into categories and pages. This is for stuff that needs lots of pictures and explanations. Aggror will probably be hired to write most of this, if he wants to.

 

 

The third database is the tutorials database we have now. A new template will be designed to display the tutorials in a nice neat format with the new site template. All the tutorials we have now will still be okay.

 

 

The front page is where you will access all of this. We'll have some nice big images you click on to go to different area, broken up like this:

 

Art Topics

Programming Topics

Tutorials

C# Reference

BlitzMax Reference

C++ Reference

C Reference

Lua Reference

 

...or something like that.

 

Sound good to you guys? I'm pretty excited about the command reference design, because it allows us to display docs tailored for each language, without it becoming too unwieldy.

[Pixel Perfect]

That sounds really good, and excellent news on Aggror doing the documentation (that's assuming he accepts).

[Laurens]

I love the design, can't wait to see the official docs this way.

[Roland]

This looks just great.

 

Then only thing I has to add is

that it would be just perfect if

keyword links was generated.

 

That means that if in the documentation

of a function or a class, another function

or class is mentioned, this would be a linked

to that other class documentation page.

[AggrorJorn]

thats an undocumented feature. what? you didn't know about that?

It's obviously a lolcat. The only problem is the forgotten caption: "U has no cheeseburger?" .

 

@Josh: Still interested to do the documentation. Hah! How cool would that look on my resumé?

 

Work Experiences

• newspaper delivery boy
  
• checkout employee
  
• Helpdesk employee
  
• IT management assistant
  
• Documentation writer for the Leadwerks game engine!
  

[DaDonik]

Looks better than the "documentation" we have now

I'm looking forward to it.