A candidate is https://wikitech.wikimedia.org/wiki/Help:Toolforge/Build_Service

This page already exists as a placeholder, and seems to me like the logical place for these docs. Does this need discussion? Have we been considering other options?

In T324815#8560149, @Slst2020 wrote:

A candidate is https://wikitech.wikimedia.org/wiki/Help:Toolforge/Build_Service

This page already exists as a placeholder, and seems to me like the logical place for these docs. Does this need discussion? Have we been considering other options?

Let's wait for the doc writers to ack, maybe @TBurmeister? (no rush, just making sure you did not forget xd)

I don't have any context on this project so I can't provide really specific guidance. My general advice is that you should structure documentation around user tasks, not around the tech you're building, so the documentation should be around things like "how to deploy your first project" and "how to set up automatic deployment" rather than "build_service". You probably already have documentation about many of the user tasks / workflows that this new service will impact, so you should look into updating that instead of creating new separate docs. So, for example, you would probably need to integrate the changes that the new Build Service provides into documentation like this https://wikitech.wikimedia.org/wiki/Help:Toolforge/Auto-update_a_tool_from_GitHub (I am just guessing; I haven't had time to really develop technical expertise in this area of WMCS yet, but hopefully you get the idea behind what I'm saying).

In T324815#8594100, @TBurmeister wrote:

I don't have any context on this project so I can't provide really specific guidance. My general advice is that you should structure documentation around user tasks, not around the tech you're building, so the documentation should be around things like "how to deploy your first project" and "how to set up automatic deployment" rather than "build_service". You probably already have documentation about many of the user tasks / workflows that this new service will impact, so you should look into updating that instead of creating new separate docs. So, for example, you would probably need to integrate the changes that the new Build Service provides into documentation like this https://wikitech.wikimedia.org/wiki/Help:Toolforge/Auto-update_a_tool_from_GitHub (I am just guessing; I haven't had time to really develop technical expertise in this area of WMCS yet, but hopefully you get the idea behind what I'm saying).

That makes a lot of sense! xd

We'll have to think about this a bit, as this building will be part of both starting a webservice, and running jobs, but there's no jobs section here: https://wikitech.wikimedia.org/wiki/Help:Toolforge (there's grid and kubernetes instead).

This might be a bit bigger than just the build service, but affect toolforge docs as a whole :/

In T324815#8594303, @dcaro wrote:

This might be a bit bigger than just the build service, but affect toolforge docs as a whole :/

I think it would make sense to push this task back to the backlog, and revisit when we're closer to launch. Alternatively, start a google doc/PAWS notebook as a draft to refine as we go, and draw documentation from it later for the wikis and tutorials.