Glottocrisio
commented
7 months ago Dear Caro, first of all thank you very much for your effort. The website looks very tidy and beautiful. I checked the document for which you asked for a review, and from my side is a full pass on all the above mentioned test-points.
If I am obliged to give some hints, then I would say that I would put the section "Running this site on your computer" at the very end, because is also something one would do "if things go wrong". I like the fact that you write as you speak, it makes everything more real, therefore easier to fathom. However, be careful to always keep it synthetic, even if it is good to make it more colorful. For instance this "Also use this process if you want to add a new page, when you’ve already drafted the content elsewhere and it’s mostly text." is important info, and you deliver it periferically. Maybe this could inserted in the title, with a slash.
Afterwards you use the expression "complicated text", and I could infer "complicated" means "not simple", and "simple" "with mostly text" from what you wrote before. Maybe there is a more straightforward way to express it.
Even if this is only for internal use, and we are all mature adults, I would put a warning in "I just want to fix a typo", to explain bad consequences of using that updating-mode for less basic changes.
I am brainstorming... you assume we have git basics, which is barely true for myself, so I can imagine that someone among us can be a bit overwhelmed with using git commands. Therefore as soon as there is time, I would extend that part, just including the git commands needed for pulling, committing and so on (I can do it after the 5th of March). If I can spot something else I will write you, and please let me know if there is some action I can take from my side, to solve this issue of tagging me here on git. Thank you for your work Caro, as a wannabe-module-writer, I feel already relieved
cloudflare-workers-and-pages[bot]
CBurge95
makkus
caro401
The target audience for these docs is anyone on the team, they should be accessible and clear to everyone (but probably currently aren't - that's what this review is for!).
You can see the page as it will be published here: https://30-how-to-docs.kiara-website.pages.dev/internal/how-to-write-these-docs
I'd appreciate review from anyone/everyone, specifically about these points below, but also any other thoughts you have.
If there's specific comments about particular words/sentences/sections, it's easiest for me if you can put them on the relevant line(s) in the markdown file if possible.
I've requested review from @CBurge95 initially (as a representative target user), as I can't add Cosimo or Petros. This might mean they don't have full write access/permissions on this repo? Review/opinions/thoughts from anyone/everyone on the team would be much appreciated if you have time!