Which style of documentation do you prefer?

[MikeHart]

Cerberus X wise I will definitely start working on the docs now. And nothing else (regarding Cerberus X).
I would love to see which style you prefer. And have a word or two below about your thoughts.

 

[Holzchopf]

I think the current one makes most sense. Would definitely not be happy with a one page per entity style.

 

[muruba]

Wiki like "confluence" is nice since it looks professional and comments can be great too.

But also having a local copy is cool (extra quick F1 look ups)

 

[EdzUp]

I would prefer the Blitz3d route where it was a page per command but with the command list down the left, each command had an example showing its use making learning the language MUCH MUCH easier.

 

[PixelPaladin]

I like the current one very much. Examples would be really nice. It is already possible to write examples, but there are not many – only in the »language reference«.

 

[MikeHart]

Wiki like "confluence" is nice since it looks professional and comments can be great too.

But also having a local copy is cool (extra quick F1 look ups)

The wiki like confluence could be achieved with the current system too by submitting push requests to the Github. Or am i seeying that wrong ?

Personally i have a huge fear with a wiki that someone could destroy the content on purpose.

Also the current process with Makedocs would not be possible anymore. So no automation regarding integration into the ide. What about integrating 3rd party modules?

I am not against wikis. Absolutely not. I just need to see the advantage in such an open system like CX is.

 

[MikeHart]

I like the current one very much. Examples would be really nice. It is already possible to write examples, but there are not many – only in the »language reference«.

So you are alking about runable examples? Means click on the example link and the cide opens up in Ted?

 

[muruba]

The wiki like confluence could be achieved with the current system too by submitting push requests to the Github. Or am i seeying that wrong ?

Probably not wrong, libgdx is doing it actually - wiki in github: https://github.com/libgdx/libgdx/wiki

Personally i have a huge fear with a wiki that someone could destroy the content on purpose.

I am not sure how it's done but my guess (maybe a naive one) is that no one but project owners would be able to approve any changes...

Also the current process with Makedocs would not be possible anymore. So no automation regarding integration into the ide. What about integrating 3rd party modules?

Yes, makes great sense

 

[PixelPaladin]

So you are alking about runable examples? Means click on the example link and the cide opens up in Ted?

That would be nice, too, but what I meant was just a piece of example code. Let's say we have the drawing methods of the canvas class and a short piece of example code that shows how they can be used. At the moment there is the examples folder, but I don't know how much it covers the commands and classes that exist. It could also be a solution to link from the documentation to example applications in the examples folder (since some commands need assets), but this would not work for the online documentation.

Something like this:

# Function DrawImage:Int(image:Image,x:Float,y:Float,frame:Int=0)
... description ...
Links: [[LoadImage]], [[DrawImage9P]], [[DrawImageRect]]
Examples: [[DrawImageExample]]

# Function DrawImage:Int(image:Image,x:Float,y:Float,rotation:Float,scaleX:Float,scaleY:Float,frame:Int=0)
... description ...
Links: [[LoadImage]], [[DrawImage9P]], [[DrawImageRect]]
Examples: [[DrawImageExample]]

# Example DrawImageExample
<pre>
example code here
</pre>

 

[MikeHart]

I would prefer the Blitz3d route where it was a page per command but with the command list down the left, each command had an example showing its use making learning the language MUCH MUCH easier.

Adding examples to each method is already possible and was done occasionaly.

 

[MikeHart]

Probably not wrong, libgdx is doing it actually - wiki in github: https://github.com/libgdx/libgdx/wiki



I am not sure how it's done but my guess (maybe a naive one) is that no one but project owners would be able to approve any changes...


Yes, makes great sense

Approving as a project owner you can only do when someone sents an update via a push request. If someone does it online, the changes are done. Of course it can be reverted.
If we use the github wiki as a the main documentation tool, then 3rd party lib module creators would need to convert to this system for their moodules and need to integrate them there or create links in the CX wiki to their repositorys. We would also need a way to create an offline version with a TED-Compatible search index. For sure, doable. After all we talk about 0s and 1s. But what about Mollusk and/or Jungle? They expect the current system.

 

[MikeHart]

Another thing you don't get with a GitHub wiki is decent syntax highlighting with a custom language like monkey/CX.

 

[muruba]

That sucks, on a side note, I noticed that github hilites "monkey" extension for gists https://gist.github.com/IvelleGames/a4038810ea53c67132088d291d10a227

 

[MikeHart]

First you need quite a bit of repositories in Github using that language and then submit a highlighter to them. There are enough monkey repros but not many CX ones. So you can forget that for now.

 

[MikeHart]

Anymore thoughts from you guys?

 

[dawlane]

For the time being I would stick with the current setup, but some of the info could do with breaking up into additional sub topics. Lets say for example App Config Settings. Breaking this up into Common for all targets and target specific sections with a bit more meaty detail would make finding information a bit quicker.

 

[MikeHart]

Thanks of all the input from you guys so far. Right now it looks like we should keep the current way and structure.

One last question about the topic. As this process will take some time, do you want sections that are done to be made public or do you want me to wait to publish till everything is done?

 

[dawlane]

I would release it in sections with updates posted in the announcements or document topics. It maybe worth while the server also serving on-line work-in-progress documentation along with the original documentation. In that way they can be proof read so any glitches and what-not can be spotted and easily fixed.

 

[EdzUp]

Release it in sections this way people can get on with it as its being done and at least get some good documentation as they work through everything.

 

[MikeHart]

Hi folks,

so keeping the current structure/kind of documentation it is. That makes it much easier on my part as the current tool (makeDocs) can be still used and third party devs don't need to adapt to something new. Thanks for everyone who participated in this little poll.
I will write again in this sub forum when I have parts done.

Till then...

Michael out!