How about "Deploy Python applications" or "Deploy a Python application" instead? I was a bit aspirational when I wrote the contributing guide, but one of the guidelines I suggested was to move toward an imperative form (or, really, a truncated question form), since it seems to be a bit more searcher friendly.

I'll go ahead and make similar notes elsewhere, though I don't know if I'd count them as blockers.

I general, I really really try to avoid imperative voice for titles in technical documentation, especially because imperative voice is used to tell the reader what to do to accomplish a task within a section. Gerund construction seems to sit better with me for informing what a section will cover. Django notably uses gerund construction. Try imaging that document with imperative voice - it's a bit harder to process.

(I'm gonna hold off on merging this until you have a chance to respond)

I think there's a trend away from the gerund in headings in technical writing, at least for task-oriented documents. The argument for the imperative form is that it's easier for readers to skim for the content that addresses their problem. By using the imperative form, a writer can align more closely with the words that the reader might use to describe their problem, rather than using the words that the writer would use to describe the problem that someone else is having. It's a little bit of trick really; while it's technically the imperative, it's being used a bit more like an infinitive (with the "to" omitted for brevity). There are some other arguments too (like differentiation in ToCs), but this is the big one.

So let's take the deployment heading as an example. Imagine you want to learn about deploying a Python application. You might ask questions like "How do I deploy my Python application?" or "What are the steps to deploy my Python application?" You can pretty readily skim for those formations. The gerund form isn't impossible, but it tends to be a bit less direct (e.g., "How do I go about deploying my Python application?") or doesn't address a task (e.g., "What is deploying a Python application?").

I think it's a good idea to write headings this way (incrementally—we don't need to go and retrofit everything at once) and since you had changed some headings anyway, I figured now was a good time to bring it up. If you're not convinced, then it doesn't need to block the merge—but then we should probably revisit the headings guidance in the contributing guide.

(Oh about that Django doc: I don't love it in either case. There's a lot going on with the ORM abstraction and what it even means to make queries when the abstraction is obscuring the fact that you are making a query. It's got problems with or without gerund headings.)

I think there's a trend away from the gerund in headings in technical writing, at least for task-oriented documents.

Can you provide some samples? I want to see this trend and how it works in practice. Please don't take this as me not believing you, I'm open to changing my stance here (which is why I haven't merged this yet), it's just that there's so many places I see gerund construction over imperative voice, and that's generally been fairly constant in my career. This could be due to bias, as my company's internal style guide explicitly calls for gerund construction. I'm okay with going against the grain, but I'm going to need slightly more convincing.

think it's a good idea to write headings this way (incrementally—we don't need to go and retrofit everything at once) and since you had changed some headings anyway, I figured now was a good time to bring it up. If you're not convinced, then it doesn't need to block the merge—but then we should probably revisit the headings guidance in the contributing guide.

We should get this right now, as changing the heading breaks deep links (which is why I wrote the linkchecker script).

I definitely want you on board with whatever we do, as I don't want to alienate a contributor on a project that frankly needs help. :)

Another suggestion is that we can do a poll on distutils-sig if we can't reach agreement.

Can you provide some samples?

Sure! I did some contract tech writing at Google recently and saw that their help centers (like Inbox or AdSense) use it often. You see it less often in their developer sites, though there are examples; I particularly like this cool tutorial listing. I've also spotted it in some major sections in the Docker documentation (see the left ToC) recently. I can find more examples, if you like.

it's just that there's so many places I see gerund construction over imperative voice, and that's generally been fairly constant in my career

I'll admit that the imperative form is a little bit trendy and the gerund is way more common. And, honestly, the gerund is not bad. I just think the imperative is a little better.

I definitely want you on board with whatever we do, as I don't want to alienate a contributor on a project that frankly needs help. :)

You're giving the idea a good faith hearing. If you're not convinced, then that's fine. Sincere skepticism or disagreement isn't going to alienate me. Though I'll admit I like getting my way. 😃

Another suggestion is that we can do a poll on distutils-sig if we can't reach agreement.

Nah, that seems a bit much. Just let me know what you think of the examples. If you're not convinced, we can update the guidance and move on.

Thanks for all of this. I can definitely see how it could work, but I'm still leaning towards gerund construction.

I'm gonna leave this PR open until Friday and if @ncoghlan or @dstufft want to chime in and let me know their preference I can be swayed, otherwise I'll merge as-is :)

I have no opinion and I am pretty sure I am not qualified to have an opinion.

I think @ddbeck is right that it's a good way to structure a how to guide, but PyPUG is kind of a hybrid of a how to guide and a reference guide at the moment, so I think it makes more sense to defer such a style change until after the restructure.

And especially for the discussions, I think the gerund form more accurately conveys the kind of content to expect - they're more "here are the trade-offs to consider when deciding how to approach this task" rather than the imperative "here is how you should approach this task" (vendors and specific projects can be opinionated on that, while PyPUG avoids choosing sides)

Cool _ I'm gonna go ahead and merge this then. We can revisit as things evolve - I'm almost convince of a bit of a hybrid - for the tutorials I think I may move to @ddbeck's suggestion.

Like before, maybe "Create and discover plugins"?

Like before, maybe "Host your own simple repository"?

Like before, maybe "Package binary extensions"?

Like before, maybe "Single source the package version"?