Comments-S

[quantlet]

Comments-S

[lborke]

There is a Latex file ;-)
You are free to edit it. Don't worry we are using GitHub version control ;-)))

[Tdannen]

I uploaded the new styleguide as pdf and tex.
It is the updated version of Sveta.

My personal opinion is, that it starts to look cryptic. Besides some minor adjustments in format it starts with the part to check code.

• the bullet points "become" commandlines.
• I think that others will get afraid of coding and back down.

I know that the argument to check the code before the meta-Info is based on logic and your experience with several Q's.

However, the Meta-Info is more friedly to start with.

Anyway, both versions are saved and open to discussion.

BG

[lborke]

We have to start writing a light version in MD-language
(https://de.wikipedia.org/wiki/Markdown) als already discussed.
Latex-Version for experts,
and an MD-version for "users".
We should make some progress in this week....

[polarstern]

But before correcting meta-info they simply have to check whether the code runs! Because if it doesn't run, it doesn't matter what they will change in meta-info!
And by the way, it is not reasonable to start with meta-info, because you don't know what the code actually does, and sometimes metainfo has completely wrong information or miss some information! In my opinion, only after checking the code you are able to understand whether meta-info is right or wrong and what's going on (at least by reading comments). So I completely disagree that they should start with meta-info. I've already validated more than 200 quantlets and I know a bit how it works...

Otherwise they should start with meta-info, then check the code, see that it's not really true and correct meta-info again! It doubles their work.

[lborke]

Polatstern says many true things.

Therefore it is a good way to make 2 versions:

1. for experts (can be more professional and practical, e.g. first functionality then the style, with a part about the complicated validation step)
2. for users (can start with meta-info), how to create a Q from the beginning. Just asuming that these people are really interested to make good and running code

[Tdannen]

I think we should draw a line between user groups like Lukas mentioned.

It should be:

• Validators (experts)
• Users (the people who submit new Q's)

Information needs of both groups:

• Validators (experts)
  ---> Validation procedure + Styleguide - as existent or even more detailed
• Users
  ---> Styleguide + plus a final checklist + appendix (including 2 examples of correct Q's)
  ---> Final check will only include several basic instructions (i.e. check if code runs properly, check if metaInfo is complete and complies with the styleguide)

I will create a second document (3-4 pages) for the users. I will try to keep it as short and simple as possible.

best regards

[lborke]

Sounds very good!
But let's do it directly in MD.
Not so important to have a good design. Most important is the info inside.
Please start it ASAP.
Next Week (~12-13.10) we should have the first draft. WH is going to make advertising for GH-Q.

I will participate in the MD draft.
We will do it of course right here, in GH.

[Tdannen]

Please check the file "userguide.md" in this repository. It represents the asked for draft.

best

[lborke]

Very good! :-)
I have already done some extension.

[polarstern]

I have also changed it a bit, see pull request.

[lborke]

Accepted!