Which style of documentation do you prefer?

Which kind of documentation structure do you like the most?


  • Total voters
    8
  • Poll closed .

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
2,845
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

Moderator
3rd Party Module Dev
Tutorial Author
Joined
Jul 31, 2017
Messages
484
I think the current one makes most sense. Would definitely not be happy with a one page per entity style.
 

muruba

New member
CX Code Contributor
3rd Party Module Dev
Tutorial Author
Patreon Silver
Joined
Jul 5, 2017
Messages
230
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

New member
Joined
Jun 21, 2017
Messages
37
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

New member
CX Code Contributor
3rd Party Module Dev
Joined
Aug 27, 2017
Messages
110
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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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

New member
CX Code Contributor
3rd Party Module Dev
Tutorial Author
Patreon Silver
Joined
Jul 5, 2017
Messages
230
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

New member
CX Code Contributor
3rd Party Module Dev
Joined
Aug 27, 2017
Messages
110
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:
Code:
# 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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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. :D But what about Mollusk and/or Jungle? They expect the current system.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
2,845
Another thing you don't get with a GitHub wiki is decent syntax highlighting with a custom language like monkey/CX.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
2,845
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.
 

dawlane

Well-known member
CX Code Contributor
Joined
Jun 21, 2017
Messages
803
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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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

Well-known member
CX Code Contributor
Joined
Jun 21, 2017
Messages
803
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.
 
Last edited:

EdzUp

New member
Joined
Jun 21, 2017
Messages
37
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

Administrator
Joined
Jun 19, 2017
Messages
2,845
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!
 
Top Bottom