tools.build cookbook feedback

[seancorfield]

Phronmophobic on Slack: use more bullet points instead of prose/run-on sentences. https://clojurians.slack.com/archives/C8NUSGWG6/p1687928614580569?thread_ts=1687926033.501479&cid=C8NUSGWG6

[steffan-westcott]

In the section "Working with Multiple Subprojects", you could mention these functions in clojure.tools.build.api as an alternative to binding b/*project-root* explicitly:

• b/set-project-root!
• b/with-project-root

[phronmophobic]

Target Audience?

Who is the target audience for this doc? In some places, it seems like the target audience is someone new to the clojure cli, but in other places it seems like it assumes the target audience is already familiar with the clojure cli and just recently finished reading the official docs :p.

Make the docs more skimmable

I would also suggest making the documentation more skimmable. I think some readers will read the whole doc from top to bottom, but I think the majority of usage will be:

1. Someone with a particular task in mind that scans the doc for the most relevant section
2. Someone who previously read the whole doc and is now returning for content from particular a section

Some suggestions for making the document more skimmable:

• Add more headers. This makes scanning from top to bottom easier and jumping to the most relevant section via the table contents
• Start sections with a short overview for that section
• Start paragraphs with what that paragraph is about

As an example:

I would rearrange the first sentence from:

With the above run and test functions in place, we can automatically run our tests for multiple versions of Clojure. We'll add aliases to deps.edn that specify versions of Clojure to test against, and then use those in a new test-multi function in build.clj.

to:

We can automatically run our tests for multiple versions of Clojure using the run and test functions. <... rest of paragraph>

---

Another example:

From:

While you can write task functions that combine multiple steps, it can be useful to work interactively with the build process, so you can run each step -- or a subset of steps -- individually.

to:

It can be useful to work interactively with the build process, so you can run each step -- or a subset of steps -- individually.

---

• Make examples more standalone. For some guides and tutorials, I think it makes sense for each section to build on the previous sections, but for a cookbook, I would expect that I could jump to the relevant section and copy and paste from there without having to read multiple previous sections. There's a couple of ways to support that use case, but I think it's important to have a good story for how someone can use the examples from the cookbook.

For example, I thought the Multi-Version Testing section sounded interesting, but realized I needed to read and grab parts of the previous section, which made me realize I needed to read and grab parts from the section before there.

Add a jargon section

Generally, I like having a jargon section. Not sure if belongs at the beginning or end.

One goal is to be intentional about:

• which words you expect the reader to know
• the order in which concepts are introduced
• for someone new, it's not easy to tell which words have a specific meaning (eg. basis, alias, tool) and which words are used in their normal sense (eg. task, command).

Here's some example jargon:

• clojure, clj: These are the names of clojure's command line tools. clj is the same as clojure, except clj is also wrapped with rlwrap to make it easier to use from the terminal.

• -X: command line option to "eXecute function".

• -T: command line option to "execute Tooling".

• build.clj: Build namespaces can have any name, but convention is that build namespaces are named build which makes the filename build.clj.

• deps.edn: The file where the clojure tools finds its config information.

• alias: ...

• basis: ...

• task?

• command?

Use Permalinks where it makes sense

I see a few links to specific code files like https://github.com/seancorfield/next-jdbc/blob/develop/build.clj. Github does offer permalink option. There's a case for trying to always point to the latest version, but I think it's probably more important to make sure links won't break in the future.

[seancorfield]

@steffan-westcott It took me a while to realize why with-project-root didn't seem familiar -- both code examples I'm familiar with (Polylith and our codebase at work) were written before that helper was added in v0.9.0 8c93e0c on Dec 22, 2022! The Polylith deps.edn file was using 0.8.3 until Joakim updated library versions in February this year and I guess neither he nor I noticed that we could simplify the build.clj file. I'll add a note in that section, showing with-project-root by default but cautioning it requires at least v0.9.0 of tools.build and show binding for earlier versions. Thank you!

set-project-root! isn't a good fit for the multiple subproject case -- it's really intended for a single project repo structure where the project root is not the repo root.

[seancorfield]

@phronmophobic Lots of good feedback there. Thanks. It will take me a while to digest and decide what changes to make.

[seancorfield]

@phronmophobic I've changed to permalinks and added a note about skipping the -X/-T section if you're familiar with that. I'm struggling a bit with your other suggestions, partly because our writing styles are very different, and partly because I don't want to duplicate that much code in build.clj. I'd be happy to review a PR with the changes you think need to be made.

[phronmophobic]

I could work on a PR, but I'm a little hesitant since, as you mentioned, our writing styles are different. There are still some suggestions that I think are a little less controversial. What do you think of a PR with these changes?

• Adding more headers
• Adding a jargon section

added a note about skipping the -X/-T section if you're familiar with that.

My philosophy is that technical documentation should assume readers are skipping and skimming which would make the note unnecessary, but reasonable minds will differ!

Anyway, I know that incorporating feedback is also a ton of work, so I'm happy to help where if I can or stay out of the way if I can't.

[seancorfield]

@phronmophobic That sounds great! Thank you. I'll be interested to see what extra headers you come up with in the PR because I glanced over the existing sections and wasn't sure what to add / how to break it down further.

[seancorfield]

Given the change made so far and the PR #50 as material for future feedback to incorporate, I'm going to close this issue out. Thank you!!