lblythen
commented
6 months ago Thanks Farshid General comments:
I suggest naming the tutorial to something like: Your first Real-Time application on Ubuntu.
Yes, done.
The tutorial chapters are served at the top of tutorial base path (e.g. /tutorial/1-prereqs, /tutorial/2-install-rtu). These links will break once we decide to have other tutorials.
Agreed, but there's a reason. You weren't to know, but I structured another project's first tutorial anticipating that same issue - and was told to lift it up to the top level until there's a second tutorial, so that's what I've done here. It won't be a big problem to drop this tutorial by one level when there's a second one to accommodate, and the content won't change so that won't require a technical re-review.
Respectfully, document structure is a TA issue; TAs need developer reviews of what we've written not how we've written it. We navigate mandates that engineering reviewers aren't aware of - sometimes against our better judgement. As an engineer I interpret mandates according to what I know an engineering audience needs, so if the result seems odd then I judged that I wouldn't get away with bending the rules.
That said, here's an exception where I'd appreciate your input. Numbering the tutorial sections (1. Prerequisites; 2. Install RTU; etc) was mandated without (I suspect) consideration of its side-effects. In particular, it spills over into the context pane on the RHS:
I doubt that'll fly. I'm inclined to revert to a normal ToC and add Daniele's usual practice: in the intro to each tutorial, he strongly encourages readers to follow the steps in order - they don't have to be numbered. What think?
RTD preview for reviewers.