HPCC-13388 Documentation for how to understand workunits

[ghalliday]

Signed-off-by: Gavin Halliday gavin.halliday@lexisnexis.com

[hpcc-jirabot]

https://track.hpccsystems.com/browse/HPCC-13388
Jira updated

[jamienoss]

c.f. comments at ghalliday#11
and those yet to be considered at ghalliday@694aedb

[ghalliday]

This document is aimed at someone who is new to the system, who wants to get a broad understanding of workunits, and a reasonably detailed overview of the process of executing a query.

This is probably easier to read and review by looking directly at the rendered file:
https://github.com/ghalliday/HPCC-Platform/blob/issue13388/ecl/eclcc/WORKUNITS.rst

Any comments welcome.

@RussWhitehead you said you were interested. Please can you review it, particularly looking for gaps in the information, bits that do not make sense etc.
@afishbeck I have mentioned manifests at approximately line 310. Please can you provide some information on what they are and when they're used.
@jakesmith please review.

[ghalliday]

A few general questions

• How should we capitalise the engines? hThor, Thor, Roxie, or all lower case - hthor, thor, roxie. Should we make a distinction between the engine name and the executable name?
• Are there terms that should be highlighted in bold/italics?

And most important...

• Should I adopt UK English usage and not have a comma after e.g.

[ghalliday]

btw I have removed the commas for the moment, but there is a similar question over spellings that vary, e.g. optimise v optimize etc.. Should we care?

[richardkchapman]

Generally the documentation is written in US english, but for internal documentation, comments, etc I don't really mind - so long as the meaning is clear.

[richardkchapman]

@shamser Please review

[ghalliday]

@shamser did you have any comments?

(Normally we annotate the pull request as we find issues/questions, even if they're subsequently clarified later in the commit.)

[ghalliday]

@shamser if you have finished reviewing the document, then please include a reference to my id, and that transfers notional ownership to me. I will then be notified that I need to look at it again.

[shamser]

Overall, very useful documentation. I've completed my review.. Thanks @ghalliday

[ghalliday]

@shamser for future reference, github generally works better if you comment on the "files changed" rather than the individual commits.

[ghalliday]

I agree dll isn't a great term - especially since most of our audience is linux based. I'm not sure what would be better
"Shared Library" could include a static library. "Shared Object" might be better - since that is the general linux term. Dynamic Library is descriptive of what it is. @richardkchapman any votes?

[richardkchapman]

They are called dylib's on OSX. I think DLL is ok so long as we spell out what it stands for for somewhere...

[HPCCSmoketest]

Automated Smoketest Build: success
HPCC Start: OK
HPCC Stop: OK

[HPCCSmoketest]

Automated Smoketest Build: success
HPCC Start: OK
HPCC Stop: OK

[richardkchapman]

@shamser Please rereview

[shamser]

Further information regarding user-defined resources should be provided or Line 317 should be removed.

[shamser]

@ghalliday Final two comments added.