Delegate + Staff crash course Markdown files

[leonopulos]

As previously discussed over email, this is the PR for the Delegate Crash Course and the Staff Crash Course. So far only the markdowns have been added. A member of the software team still has to link the generated PDFs in the staff panel on the WCA website.

I hope I opened this PR correctly. I merged with the other PR first, and then simply added the markdown files. Please let me know if there need to be any changes, in order to ensure correct merging of both PRs in the end. :)

[Jambrose777]

This looks like it changes the delegate crash course to be completely hard-coded. Before the individual teams modified their own sections to instruct Delegates. Is this going away? Have there been discussions with the relevant teams to ensure that this version of the crash course is sufficient?

[leonopulos]

I would not say that it is hard coded. Individual teams can still reach out to the WQAC about a change, or even send in their own PRs. The content of the markdown file is not set in stone forever.

I don't think I understand your second question. This file contains the exact same content the Delegate Crash Course on the website currently has, so why would we need to double check with teams to make sure it is sufficient?

[Jambrose777]

I would not say that it is hard coded. Individual teams can still reach out to the WQAC about a change, or even send in their own PRs. The content of the markdown file is not set in stone forever.

I don't think I understand your second question. This file contains the exact same content the Delegate Crash Course on the website currently has, so why would we need to double check with teams to make sure it is sufficient?

Hard coded -> that the document is uneditable on the website and the only way to make changes is to edit the code. Right now the crash course is set up to be modifiable by anyone who has permissions to do so.

I didn't realize it is the same, if that's the case then the text doesnt need to be approved, but I'm still not understanding why it is being moved to it's own hardcoded document.

[DanielEgdal]

I'm still not understanding why it is being moved to it's own hardcoded document.

@Jambrose777 there is a bit of a longer story to this. Roughly a year ago WQAC completed a document for Staff to introduce them to their roles (i.e. a Staff Crash Course). When it came to adding it, it was highlighted that this needed to be stored the same way as the Delegate Crash Course.
After discussion with the Board, the conclusion was reached to place both of them on Github.
One of the big pros in this is also that we will now have an edit history in this so we can note changes.
Though these documents are mostly of use for WCA Staff, it was also mentioned to be a pro that people in Training or interested in the WCA could be directed these documents via GitHub without any WCA Staff member needing to leak the contents from the website.
There are likely more points than this, as this has been a very long process to come to this, so this is not a complete reply but a part of the thought process.

[cubewhiz]

@DanielEgdal That sums it up nicely.

[viroulep]

Just (finally) having a way to author and timestamp each change to these documents is enough to move it to version control in my opinion.

But I do agree with Jacob that we should discuss/inform the relevant team about that!
It's also unclear to me how you plan to have changes made to the Delegate crash course:

• should the committees send a PR here?
• what if some committee can't do that?
• while the WCA official documents definitely need the Board review/approval, for the other documents (crash courses, tutorials) I would assume the simple fact a committee member submit some changes on behalf of their committee should be enough; in that case should we just consider that if the change is valid technically we should approve it?

It's probably good to make sure the proposed plan has a consensus before actually going forward with it (or going forward without a clear plan :p).

[viroulep]

@leonopulos could you please upload a pdf of how it looks like locally for you? (as well as the wkhtmltopdf version used)
The page break div just messes up the document completely and I just have the content up to the first page break.

[viroulep]

Actually it's pandoc which turns the <div ...>\pagebreak</div> into <div ...>...

[viroulep]

I've just pushed an update to the styling; pandoc doesn't support attributes on all items, but headers/div/images support them, so I think we can get away with putting some page-break-after/before one them!

[viroulep]

@jonatanklosko since more PR are gonna come from external branches, I wanted to activate travis on pull request.
I then realize the current script wouldn't work on such build because of environment variables, and moved the key decryption to a before_deploy target, do you see any issue or concern with that?

[leonopulos]

I just changed the mail addresses. If I understand everything correctly, that's all you needed from me, i. e. no local pdf from me is necessary anymore.
@viroulep Thank you for the styling adjustments you did! :)

[viroulep]

Thanks, no problem!

I still think a discussion with relevant committees about the process to edit these files is worth having before making the switch ^^

[jonatanklosko]

I then realize the current script wouldn't work on such build because of environment variables, and moved the key decryption to a before_deploy target, do you see any issue or concern with that?

Sounds perfectly reasonable to me! That ensures the build doesn't fail, but do we also need the PDFs preview? In such case we could look into Netlify as it allows for per-PR preview (i.e. we could generate an index.html listing all the documents, so that one could easily navigate to the PR-specific website build and click around to see the PDFs). Just throwing in the idea, perhaps we're happy as long as the build passes, as Markdown is perfectly readable.

[viroulep]

Let's have this discussion in #155 :)

[leonopulos]

I still think a discussion with relevant committees about the process to edit these files is worth having before making the switch ^^

Right, the WQAC will discuss and inform the relevant teams about this change. The most consistent way would probably be to have us manage all changes, and if teams need to update something, they reach out to us with the changes they would like.

Another thing that popped to my mind just now: Once all these changes finally go into work, the certificate templates should be published alongside the competitor-tutorial. I'm not quite sure where the best place to store them in the back-end would be though.

[viroulep]

I'm not quite sure where the best place to store them in the back-end would be though.

I don't have a strong opinion about this, if they are just pdf that needs to be distributed "as-is" I guess we can just put them here.

[Ivan-Brigidano]

One small question/suggestion: wouldn't it be better to name "Committees and Teams" capitalized (instead of "committees and teams")?

[viroulep]

@thewca/board can you provide a review for this?
As far as I'm concerned the technical part looks good to me.

[viroulep]

LGTM, hopefully this will unlock the merge button :p