Overhauling CerberusX Documentation

[Phil7]

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]

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.

 

[MikeHart]

Damn i have nothing to say. Loving it.

 

[MikeHart]

What do you have in mind for getting started?

 

[Rich]

I really like that structure. great work

 

[Paul59]

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

 

[Phil7]

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]

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]

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]

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]

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]

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

 

[MikeHart]

Cuts out a lot of why/what/when words

Lol Paul, read your example again.

Personally i would use Phil's approach too but Paul's is also fine.

 

[Phil7]

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]

[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]

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

 

[Paul59]

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!

 

[Paul59]

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]

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]

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.