Documentation needs more concrete example of KSY compilation

[FilipDominec]

I suggest that the main page would be more verbose concerning the phrase

 "this .ksy file can be compiled"

This few words skip quite a lot of steps that need to be done! Again, in the more technical part of the page, it states

"Compile .ksy file into target language source file and include that file into your project"

... but no particular links or commands are provided.

In fact, I found it quite hard to find all information to get the compiler work on vanilla Ubuntu system.

Perhaps we could mention that there are many options to get it and run it, but then give the user one particular step-by-step example on how to compile .ksy files?

[GreyCat]

Thanks for your suggestion!

If you mean http://kaitai.io/ page — then it's not supposed to be a very detailed step by step explanation, it's there to demonstrate the overall concept, so I'm not sure that it's a good idea to put it there. Probably those who would want detailed instructions should refer to user guide + per-language instructions (I know that these are lacking as well, but that should be fixed).

"this .ksy file can be compiled" This few words skip quite a lot of steps that need to be done!

This can be done in at least 3 ways:

• compile using an online compiler — probably that's the easiest way for introduction purposes
• compile using web IDE
• compile using "desktop" compiler: this, in turn, is slightly different on various operating systems

May be it might be a good idea to provide a link to the first one, but dealing with (2) and (3) is way too verbose for a concise introduction.

"Compile .ksy file into target language source file and include that file into your project" ... but no particular links or commands are provided.

This is definitely out of scope of "quick peek" introduction. There are myriads of compilers, IDEs, build systems, OS combinations. I don't think that it's a viable idea to write down all of them.

We're mostly targeting intermediate-to-advanced developers, so if a developer struggles with inclusion of a source file into a project in his/her own language of choice, chances are that even if we'll provide detailed instructions, he/she will encounter much less trivial obstacles with generated API a bit later.

@koczkatamas @LogicAndTrick Any thoughts?

[FilipDominec]

Thank you for your quick answer. I believe that including the three aforementioned bulletted options is exactly what is needed.

[koczkatamas]

@FilipDominec please help me understand the problem a bit more.

Is the main concern that it is not trivial to find the link to the documentation (http://doc.kaitai.io/) on the main page (http://kaitai.io)?

Or would it be more logically correct to include it after the "this .ksy file can be compiled" sentence too?

Or does the documentation itself fail to describe clearly enough how to compile it on your system?

If I understand correctly the issue, what do you think, would it be enough to make the text "can be compiled" into a link which points to http://doc.kaitai.io/user_guide.html#_installation_and_invocation ?

[FilipDominec]

I believe there is some well-though system in the project pages, but I wanted to share my personal experience of a newcomer. I feel the documentation to be dispersed among too many domains, which naturally leads to some confusion about which one is the right one to start with.

I started off at github, and eventually opened about 10 different kaitai-related tabs in my browser. I had to sit for a while and make it clear for me which of these contain duplicate information , which contain information irrelevant for my simple case, and eventually which get me an usable kaitai compiler on my computer.

Perhaps other users, as well, would spare some time if: 1) the "This .ksy file can be compiled it into" phrase linked to the ways of doing so, perhaps https://github.com/kaitai-io/kaitai_struct_compiler or some part of docs 2) https://github.com/kaitai-io/kaitai_struct_doc/blob/master/user_guide.adoc and http://doc.kaitai.io/user_guide.html#_installation_and_invocation were either marked as duplicates, or the Github page just linked to the second one, 3) https://github.com/kaitai-io/kaitai_struct and http://kaitai.io/ were similarly marked as duplicates, or the Github page just linked to the second one

But take it just as my suggestion. I really appreciate your work you put in the project.

[GreyCat]

https://github.com/kaitai-io/kaitai_struct_doc/blob/master/user_guide.adoc and http://doc.kaitai.io/user_guide.html#_installation_and_invocation were either marked as duplicates, or the Github page just linked to the second one,

These are actually the sources and rendered version. We can't really "hide" them, as we're open source project, anyone can contribute to documentation as well.

https://github.com/kaitai-io/kaitai_struct and http://kaitai.io/ were similarly marked as duplicates, or the Github page just linked to the second one

Probably that's a good idea to reduce duplication and just redirect people from our umbrella project's GH README page to kaitai.io, as it is definitely much better maintained than that old README.

[FilipDominec]

OK, thank you for your consideration.