Overhauling CerberusX Documentation

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
644
So I will go with language guide then. Thanks for the feedback.

The sequence that topics are introduced and how they are grouped is even more important

There is a link to the language guide in the first post. The content is mostly the old stuff, but I changed the sequence and the grouping a lot.
Your other comments look a bit vague to me. There are definitely different needs to be met for beginners and experts. For that reason I wrote a quick guide to the language for the experts and I try to write as easy as I can so every beginner should understand the language guide at least if read from start to finish.
 
Last edited:

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
924
if you make the text for beginners in mind, then experts can can use it without any slowdowns as long as there's a basic section and a separate more-detailed section that's easy to skip when you're an expert on the subject.

I would really like a description of the language to read as if I read about Cerberus-X for the first time and that each section starts by covering everything that there's to know using as few words as possible. When you're an expert you could use the same text using visible keywords inside each logically grouped section.

And placing a short example between the beginner and expert-text would always be useful for both, so you don't have to remember any details. That's a key idea I wanted to bring to the table, it's just an idea. Hope this fleshed it out abit better.
 
Last edited:

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
644
I had similar ideas when I was starting with this. Did you read into the language guide?
I am still not sure if I understood you correctly. Maybe I need an example ;-)
What do you mean by visible keywords? Highlighted or bold important words that transport the message?

Here are some thoughts that came up when trying my version of beginner and expert paragraphs covering the same topic:
- How to deal with intermediate programmers?
- How to get from beginner to expert by reading the guide?
- What about technical terms? They make experts understand quickly while leaving beginners frustrated.
- What about the stuff that is written in an easy language for beginners? Should I put the same content in a more detailed way into the expert section?
- What is the stuff that a beginner has to know? Where to make the cut?

These thoughts are the reason why I am on a different route now. Maybe I can sketch out my current approach next time ...
 

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
924
I'm sure you don't need my tips, but I was thinking.. pick a any retro manual that had BASIC in it, they go from variables to loops to you know, anything that you need to know and explain how they go together.

That's the most important thing when you're a a beginner. Intermediate users wants to know data structures more indepth, and also not be exposed to a sea of API's just yet, they want useful graphics examples which inherently use the API' they probably will use for themselves (they are not that many I would say) 80% of a game is made of 20% of the API and commands. You know what I mean..
The expert wants an overview of all API's (of course there cannot be a through example for each, but maybe more advanced examples that group many APIs/commands together after they have been very briefly presented. So you have like a thin index with their parameters, and now and then you have a semi-fat example that uses a good bunch of those to do something intersting.

But I would really like if there was a manual feel to it.. you know? You re-read it as a beginner, then as a intermediate, and then as an expert. Data-structures should be the most important thing for "intermediates" I would say. And it should be like a manual in itself almost.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
644
I'm sure you don't need my tips, but I was thinking.. pick a any retro manual that had BASIC in it, they go from variables to loops to you know, anything that you need to know and explain how they go together.
I surely do need your tips. If you are to deeply into something you definitely lose the ability to see it from a beginners or intermediate perspective.
Talking about the form of a manual, I thought the structure of the Language Guide is already heading in this direction, it just needs to be fleshed out. If you are looking at the pages of the Headlines you will see that I tried to give an overview about how things go together. I also tried to put it into an order, so everything mentioned in a later chapter is explained in an earlier chapter.
Maybe it is best, if I post here, when a chapter of that is finished, so you can give some feedback specifically...

80% of a game is made of 20% of the API and commands
This is especially true for beginners, that's why I want to write a tutorial and a beginners guide similar to Invader Jim's videos to cover that.
 
Last edited:

Dabz

New member
Joined
Aug 3, 2021
Messages
18
I like documentation that allows user examples of the keywords/functions of a language to be added, as a great example, I hate PHP really, but, use it... I digress [I do that a lot], anyway, yeah, when you look at their docs, there's always heaps from other users on how to use functions, and just by looking at an example the purpose clicks instantly, also, you spy a clever little trick or two, other/better ways of doing things, I've learnt literally loads from them in the past and so, allowing users to implement their own examples of a certain keyword/function would be great if you ask me.

My 2p

Dabz
 

Jimmy

Active member
3rd Party Module Dev
Tutorial Author
Joined
Jan 2, 2020
Messages
924
I would second that user-examples would be great way also to off-burden the one or few people that otherwise also have to write the examples themselves. I can imagine writing some examples, maybe we run them by some quality test or something, to make minor adjustments and make sure they follow the same style or at least one of few very readable styles.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
644
I don't plan to write an example for every usecase of a command or function, but at least one minimalist example to see the gist of it and one that shows how it can be used in a more complex situation. When I am am finished with these I am completely open to user-examples because the existing examples will then hopefully reflect a constistent coding style to provide some guidance.
 
Top Bottom