Overhauling CerberusX Documentation

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
I am rewriting the documentation. Here is the link to current state of the new docs.

My goals are:
- Better structure for easier access of information (Fewer categories. Avoid redundant information. Avoid circular links.)
- Make it more beginner friendly (Less expected prior knowledge. Each chapter starting easy. More examples. Fewer tech words.)
- Implement important forum information into the docs

My plan is to follow this order:
- home page structure
- the language reference
- fleshing out the topics of the home page
- optimize the stylesheet (better overview, dark and light theme)
- optimize the output of the makedoc generated docs for modules, classes etc.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
For now there is only the home page with the main topics and the structure of the Reference Guide (formerly Language Reference). The content of the Reference Guide is just the old content spread around to the new structure. My goal here is to have about one to two pages of content on each subpage.

I'd like to hear what you think about it now, because when I start into editing the content, I would like to avoid big changes to the overall structure.
 

Rich

Well-known member
CX Code Contributor
3rd Party Module Dev
Tutorial Author
3rd Party Tool Dev
Joined
Sep 9, 2017
Messages
451
I really like that structure. great work
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
Will there be a complete index? Sometimes I find it easier to look there rather than work out where in the docs a particular thing is discussed!

Personally I think using Strict mode is better for examples as there's no doubt about types and expected values even though it's more verbose.

This is probably not a good example for beginners on the Strict mode page as there is no clue about what GetDate() returns (that syntax looks a bit odd to me too!):

Print "the year is "+GetDate()[0]

I'd break it down by assigning the function result to a string array then indexing that.

I know it's early days regarding content but I happened to notice it :D
 
Last edited:

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
There can be a complete index, if some of you don't want to miss it. You are talking about alphabetical order, right?
Could you provide some examples, where the index is the best way to find information? Maybe we can avoid getting back to it by replacing it with a combination of a better F1 lookup help and some overview tables (usage/kontext categories)

What do you have in mind for getting started?

I am thinking about two ways to categorize stuff there. One is by media type (Videos, Tutorials, HowTos, Examples), because most people prefer one kind of explanation over the other. The other is by level of programming experience, because you want the tutorial to fit regarding the level of knowledge.
Maybe there is a way to mix both ...
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
Personally I think using Strict mode is better for examples as there's no doubt about types and expected values even though it's more verbose.
Same opinion here. I am going to edit all the content including the examples and they will allmost all be in strict mode. Plus, in the chapter for strict mode I am going to recommend it as the standard way of writing and publishing code for CX.

If you want to proof read the content, please wait for my editing. I will post here when I finish a piece worth reading.
It will definitely need some native speaker editing to enhance quality.
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
You are talking about alphabetical order, right?
Could you provide some examples, where the index is the best way to find information?
Yes an alphabetical index. I don't think it's the best way to find information but it can be handy. If I wanted to find a color name for example I could go the long way round... API Ref->mojo2->mojo.color->mojo.colornames or (because I know it'll be COLOR_something I can look in the index much more quickly! If there's no index it would be much harder to find, especially for a beginner. A searchable index would be better still although if it's a single page html version Ctrl+F would do the trick :)
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
So the index is just better than nothing, if there is neither proper autocomplete functionality with F1 help system nor searchable documentation, right?
The current index is generated automatically, therefor no additional work is needed to keep it for now. But I would not keep it as prominent as it is now, still in the reach of one or two clicks.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
Next update: Direct link to the reference guide
I wrote some introductions to each chapter in the reference guide. But I am not satisfied with the links so far.


How do you feel about the phrase

We will be talking about...
* how to do some stuff

as the overview of the subtopics of each chapter?
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
How do you feel about the phrase

We will be talking about...
* how to do some stuff

as the overview of the subtopics of each chapter?
"Topics covered" or "Subjects Covered"?

For example, (condensed the Basic Program Structure page):

Topics covered:
  • why all the example code uses "Strict" mode.
  • a minimalist working code example.
  • where and how to add comments to your source code.
  • when and where to add line breaks into a code file. [do you mean white space??]
  • choosing names for your files, functions, variables etc.
  • using a consistent coding style to make your programs easy to understand and maintain.
Cuts out a lot of why/what/when words :D
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
I tried to get a more personal tone into the docs, but your suggestion is better. Let's see how I am doing with the other "topics covered".

Some why/what/when words might still remain, because often it is the purpose of a language feature that is not mentioned in the docs.
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
Messages
552
[do you mean white space??]
No, it is about the options of having multiple statements in one line and the options to break a line inside a single statements.
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
Lol Paul, read your example again.
I was showing how to condense the text, personally I'd re-write/combine some of those bullet points anyway - but what do i know, I've only spent a lifetime writing advertising/marketing copy and written eight books :p
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
No, it is about the options of having multiple statements in one line and the options to break a line inside a single statements.
Urghh, I've always hated the multi-statement line concept - should be expunged from CX and every other language! :D
 

Paul59

New member
CX Code Contributor
Joined
Dec 13, 2018
Messages
375
Looking at 'Variables and Constants' page it seems you're shooting for a complete beginner's guide to programming. That's a huge job and I'm not sure it's really necessary in these docs as I'd imagine most users will have been introduced to programming via some other language.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
2,845
I tried to get a more personal tone into the docs
I did the same in my book. It was well received. At the end it is your decision to make. As YOU put in the work.

I've only spent a lifetime writing advertising/marketing copy and written eight books
Yeeez Paul, did you really got offended and need to prove yourself? I just found your remark about "cutting out whys/where/whens" and then reading "why where etc." in your list somehow funny.
Anyway, congrats for that achievement (writing 8 books). After only 5 books my wife and I wrote together, we know how hard it is to write even one.
 

MikeHart

Administrator
Joined
Jun 19, 2017
Messages
2,845
That's a huge job and I'm not sure it's really necessary in these docs as I'd imagine most users will have been introduced to programming via some other language.
We want to make CX more easy for beginners. Experience users can easily skip through these things.
 
Top Bottom