"Generated" or "Built"


#1

I’m writing for a non-technical audience, and trying to describe the process of generating documentation from source code.

Which one makes more sense:

  • “Once documentation is cloned from your source repository, it is generated and hosted on our site”
  • “Once documentation is cloned from your source repository, it is built and hosted on our site”

Also curious about a better word for “cloned” here. Pulled? Accessed?

Words are hard,
Eric


#2

For the first question, I’m inclined to recommend “built,” because it’s shorter and less code-ish. (Also, for the case where a more technical reader might encounter it, “generated” tends in context to imply “generated-from-code,” even though that’s not the workflow you’re describing here.)

I’m pretty sure it’s clearer to translate, too , if L10N is a concern.

For “cloned,” I’d recommend “copied.”

In the interest of a bit more clarity and general precision, too, what about this for an overall edit:

“After the documentation source files are copied from your repository, the doc set is built and hosted on our site.”


#3

Second those suggestions, although for a non-technical audience, I’d say “documentation” is better than “doc set”, and I would try to avoid the passive voice. Who is doing the copying and what triggers the build?


#4

The argument for the passive voice here is that the system is doing the copying and building – or script, or some other entity that you would have to anthropomorphize to avoid the passive voice.

I tried to write around “doc set,” and only made things worse – sometimes too much precision obscures as much as too little.

Wording hard :confused:


#5

Thanks for the comprehensive replies! Lots of good feedback :slight_smile: