Overhauling CerberusX Documentation

[Paul59]

We want to make CX more easy for beginners. Experience users can easily skip through these things.

Yeah, it's just a big job to do it properly and I wonder if the effort would be better spent elsewhere.

 

[Paul59]

Yeeez Paul, did you really got offended and need to prove yourself?

Eh? Not offended and nope, I have nothing to prove just pointing out that I've had lots of practice.

 

[Phil7]

@Paul59 Thank you very much for your thoughs on these first drafts. So you are an experienced writer and native speaker, right? That's perfect for this project.

I've always hated the multi-statement line concept

I don't like it either, but as it's in the language I have to cover it at least in the reference.

Looking at 'Variables and Constants' page it seems you're shooting for a complete beginner's guide to programming.

Experience users can easily skip through these things.

I guess you can't have a really useable reference guide and at the same time cover all the things a beginner needs to understand, but I try to write the introduction on each topic as easy to understand as possible. If the first lines of a chapter are hard to grasp for a newbie they won't put in the effort to go any further. An other thing is that I want the reference guide to cover most things you need at least once to avoid too much switching of information sources.

This is from the "How to use the Guide" chapter.

If you are new to Cerberus X or programming in general and you want to get a deeper understanding of the language, the best way to read it is from start to finish using the forward links at the beginning and the end of each page. This is due to the fact that later chapters require at least a basic understanding of the concepts discussed in earlier chapters.

 

[Holzchopf]

I'm sure this is going the right direction. But here's a small "layout" wish: instead of having the sub-topics in a line, separated by "|", I'd prefer having lists with one entry per line. Just a personal preference.

Edit oh and concerning the alphabetical index: That's where F1 leads to, if the keyword is ambiguous. I guess keeping it for that sole reason is reason enough.

 

[Phil7]

I'd prefer having lists with one entry per line

I tried this first, but it did'nt work out well. It took way to much vertical space, even with minimal margins between blocks. Even though I am open to layout suggestions and I will try to present a mockup with this.

That's where F1 leads to, if the keyword is ambiguous. I guess keeping it for that sole reason is reason enough.

I won't ditch this unless it is replaced by something substantially better. In the long term it should be replaced by either a better F1 help or a searchable help site. To me this index is like looking up your aunts number in an old telephone book.
Don't get me wrong. It can still stay in a less prominent place of the docs, if someone simply likes this way of working.

 

[Phil7]

Here is the mockup. Besides the fact that multicolumn is badly implemented in browsers (no column break afaik), you need 3 columns to fit all the stuff in there if you prefer lines.

 

[Holzchopf]

I prefer the layout on the left =)

 

[Phil7]

I have to admit, I also like it. Didn't try 3 columns before.

But I would like to keep the side by side style on the sub-pages. What do you think?

 

[MikeHart]

How does your columns behave inside TED with different sizes regarding the tab with?

 

[Holzchopf]

At least TED 2018-12-29 supports columns

 

[Phil7]

For now columns are just a proof of concept. I did a bit of research and it seems they are not a proper solution. I couldn't set breaks to make headlines stick to their content and at the beginning of the first column there is a large horizontal gap. Maybe there are some workarounds for this, but there might be solutions with blocks and media queries or flexbox.
I think this is something that can be changed at any time.

Edit: ... and at the beginning of the first column there is a large horizontal gap. --> should read "... vertical gap."

 

[Holzchopf]

One workaround is: Put the headlines and content into a div with display: inline-block; and width: 100%;

However, this stops the columns from stretching when they could be a little wider than specified.

Tested in Opera which uses the same engine as Chrome

 

[Phil7]

I want to tackle the examples folder and reorganise things. Are there any licenses to them that could prevent me from altering the sources or renaming the files? I will look through them and respect everything I find, but renaming is definitely a thing I have to do.

 

[Holzchopf]

You're talking about the "Cerberus/examples" folder, right? If you're talking about "Cerberus/docs/html/examples" please keep in mind these are auto-generated and auto-named, which is why it (imho) makes sense to have a naming scheme which is admittedly a bit cryptic but on the other hand prevents collisions.

 

[Phil7]

You're talking about the "Cerberus/examples" folder, right?

Exactly. To be honest, I'd prefer most of the examples to be inside the docs and only a few to stay in this Cerberus/examples folder if they are something like a showcase of a game project or to show off the capabilities of CX. So it would change to something like a showcase folder.

 

[Wingnut]

I'd prefer most of the examples to be inside the docs and only a few to stay in this Cerberus/examples folder if they are something like a showcase of a game project or to show off the capabilities of CX. So it would change to something like a showcase folder.

I agree, most examples are micro-examples showing off some simple feature.

Those examples would fit better inside the documentation.

 

[Phil7]

I have a problem choosing a suitable name for the language reference. To me this name is not optimal, but I am not sure which one is the best:
- language reference
- language manual
- language guide
- language reference guide
- language reference manual

I would prefer language guide, but I don't know if it fits the fact that it is the in depth description of the programming language and not some introduction guide.

 

[MikeHart]

+1 for language guide.

 

[Wingnut]

I would say ; always keep the main skeleton of the text to as few words as possible. It should consists of mostly meaningful keywords with a well defined structure that beginners can understand and a minimum of noise.


Then add some personal touch on top of that..

 

[Wingnut]

The sequence that topics are introduced and how they are grouped is even more important, but the document should feel rigid and be easy on the eyes (for both beginners and experts alike).