New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-organize existing documentation into new structure. #318

Merged
merged 1 commit into from Jun 13, 2017

Conversation

Projects
None yet
4 participants
@theacodes
Member

theacodes commented May 31, 2017

Towards #317.

Content is unchanged in renamed files, except for a few page titles that were renamed for consistency.

After this PR is merged, a new PR to re-writing the landing page to better surface the docs will be created, so don't sweat the landing page so much right now.

I will create all redirects on RTD once this is merged (ugh I hate that this is manual).

This is staged here: http://temp.theadora.io/pypug-reorg/index.html

@theacodes theacodes requested review from ddbeck and ncoghlan May 31, 2017

@theacodes theacodes referenced this pull request May 31, 2017

Closed

Master documentation plan #317

6 of 6 tasks complete
@ncoghlan

Approved without merging, as it makes more sense for you to merge this at a time when you're ready to make the necessary RTD adjustments.

@ddbeck

ddbeck approved these changes May 31, 2017

A few notes about a way headings might be improved, but no major worries with this. Thanks for your work on this!

Application Deployment
======================
=============================
Deploying Python applications

This comment has been minimized.

@ddbeck

ddbeck May 31, 2017

Contributor

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.

This comment has been minimized.

@theacodes

theacodes May 31, 2017

Member

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)

This comment has been minimized.

@ddbeck

ddbeck Jun 1, 2017

Contributor

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.)

This comment has been minimized.

@theacodes

theacodes Jun 1, 2017

Member

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.

This comment has been minimized.

@ddbeck

ddbeck Jun 2, 2017

Contributor

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.

This comment has been minimized.

@theacodes

theacodes Jun 7, 2017

Member

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 :)

This comment has been minimized.

@dstufft

dstufft Jun 7, 2017

Member

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

This comment has been minimized.

@ncoghlan

ncoghlan Jun 8, 2017

Member

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)

This comment has been minimized.

@theacodes

theacodes Jun 13, 2017

Member

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.

Plugin creation and discovery
=============================
================================
Creating and discovering plugins

This comment has been minimized.

@ddbeck

ddbeck May 31, 2017

Contributor

Like before, maybe "Create and discover plugins"?

@@ -1,7 +1,7 @@
.. _`Hosting your Own Simple Repository`:
==================================
Hosting your Own Simple Repository
Hosting your own simple repository

This comment has been minimized.

@ddbeck

ddbeck May 31, 2017

Contributor

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

Binary Extensions
=================
===========================
Packaging binary extensions

This comment has been minimized.

@ddbeck

ddbeck May 31, 2017

Contributor

Like before, maybe "Package binary extensions"?

@@ -1,7 +1,7 @@
.. _`Single sourcing the version`:
===================================
Single-sourcing the Project Version
Single-sourcing the package version

This comment has been minimized.

@ddbeck

ddbeck May 31, 2017

Contributor

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

@theacodes theacodes merged commit d2e538e into pypa:master Jun 13, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@theacodes theacodes deleted the theacodes:reorg branch Jun 13, 2017

ncoghlan added a commit to ncoghlan/python-packaging-user-guide that referenced this pull request Jun 24, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment