Python.org Redesign Request for Proposals | Hacker News Reader

Python.org Redesign Request for Proposals

pythonorg-redesign.readthedocs.org

125 pointsjnoller64 comments

<shameless plug> A couple years back I was working at Bug Labs and we relied heavily on the Openembedded project. We contributed source code patches as you would expect, but one unique contribution was having our designer make a new logo for Openembedded. You can see it on their website today. </shameless plug>

This doesn't seem to occur to people very often, but if your company is relying on an open source project, source code patches are not the only way to contribute back.

Can you spare some time from your designer? Help out with a logo or website design work.

Do you have a doc writer? We all joke about RTFM, but if there is no manual that doesn't help much.

There are some things that developers don't necessarily want to do, so those areas often lack on open source projects based on volunteers. A company using their resources to fill in some of the gaps helps a lot.

I also don't understand why designers will compete on 99designs but don't seem to contribute to open source that often. If you are trying to break into the industry by showcasing your work, why prefer the 1 in 30 odds of having your design chosen in a crowd sourcing competition over actually helping out an existing project?

Some programmers passionately believe that contributing to OSS is status-increasing, perhaps enough to be a self-fulfilling prophecy. I have yet to meet a designer who believes this.

There exist UX paths by which contributing to OSS via code is easy, obviously wanted, and generates warm fuzzies. The fork-and-go experience of adding one marginal feature to a gem for Ruby then sending a pull request feels like ponies and sunshine every step of the way. By contrast, there exists no infrastructure or UX to support designers contributing in the same way. You probably have to send an email to a project maintainer. Try sending ten of those: report how sunny your ponies feel as a result.

OSS projects, in the main, very aggressively signal that they do not care about design. Just having a logo makes it look like you have super-anomalous levels of care relative to OSS. Designers pick up on hints like "your web presence is a default Github page" and "your logo was created by a programmer in MsPaint" to decide that their talents are probably better applied elsewhere, where they will be valued.

Also, 99designs will pay more designers more money today than entire communities of OSS developers will this year. Even starving artists can do the math.

I think just as large a part is that it's difficult for multiple designers to contribute to a project in a meaningful way without stepping on each others' toes. Do designers often collaborate in groups of more than two? (Layer Tennis is the only thing that comes to mind)

If I were evaluating a project I would choose a project with a default Github page over a project done in MSPaint just because there's a good chance that the latter was written by a developer who likes the MSPaint logo.

One thing that would really make the website work better is to make pages like http://docs.python.org/library/stdtypes.html hierarchical with an overview and one or two sub levels so each function gets its own page, making it easier to find via search (The Google) and do dynamic linking from IDE:s or whatever if the url routing were set up smart.

Today when you search for 'random.choice python' you get to the random front page with 20+ random functions forcing you to first click on the google search result (probably with a lower CTR than if you have had the function name in the title) and then when entering the docs page hit CTRL+F and do a page search for 'random.choice'. That would make my life easier, and annotated documentation, preferably with some kind of "like"-functionality pushing the good answers up. I do get however that some people like to have the full spec for all random functions in one page...

See: https://twitter.com/ncoghlan_dev/status/205290363437580289

The first thing I do when learning any piece of technology is putting all the docs into a mindmap, e.g. here is one I made the other day for Jinja2:

http://www.alexkrupp.com/Jinja%20docs.html

FreeMind .mm file: http://www.alexkrupp.com/Jinja%20docs.mm

Ideally the HTML of the Python docs should be structured in such a way that the all the built-in functions, string functions, regex functions, etc. can be dumped into a mindmap automatically each time the documentation is changed.

I like it! How did you create the jinja html? Did you first create the .mm and then export to html somehow? Or did you have to create it manually?

I created it manually using FreeMind. I basically just copied and pasted each section from the docs, and then grouped some of them together in logical ways to make it easier to read. I also deleted most of the usage notes about how previous versions worked, since I was starting with the newest so all of that was irrelevant to me.

Yes, it'd be nice if that search went straight to the function in question -- however, it'd make the docs a lot more broken up and IMHO harder to use if each module had 15 sub-pages for the individual functions. Harder to scan or Ctrl-F on the page, for one thing.

Often when I need to lookup something in the docs it is a specific function, I do not want scan large blocks of documentation for a whole module, internal linking to similar functionality and all other functions in the module reachable with one click would solve two problems for me: 1. Take away the information overload you get today when searching for specific documentation on one thing and 2. Make all the other things reachable in one click, CTRL+F + Click.

Another solution could be to keep the pages as they are today but the possibility to click down the hierarchy to get to a more in-depth function-page where you can get comments, solutions, examples etc. This would cater for both tastes of documentation consumption. This would also solve the problem with coming into the docs from search, making it easier to get a 100%-hit directly when searching for a specific function.

> Today when you search for 'random.choice python' you get to the random front page with 20+ random

I prefer a single page for random than having 20 something pages for random.x. Here is the doc for random.choice:

    random.choice(seq)
    Return a random element from the non-empty sequence seq. If seq is empty, raises IndexError.

A separate page for this will be textbook definition of overkill.

If you already know what you are looking for(random.choice), a better way to lookup the docs is to either use the repl(help(random.choice)) or configure your editor to lookup the documentation. Python library docs is mostly contained in the docstrings.

As you see in my comment, I do not agree with you, but realize that "some people like to have the full spec for all random functions in one page...".

It is not overkill as I see it, a page for random.choice with official documentation and annotations and comments would be good in my book.

If you’re concerned about locating information quickly via Google, maybe thinking of how sites like the Stack Overflow family work, then having many pages is one possible idea. However, I would worry that this is restricting the design purely to accommodate today’s search engines. Using many small pages would surely reduce the usefulness for users who prefer browsing to searching.

Since HTML5 provides several new tags to help define the outline of a page and specify suitable headings to go with it, I’d probably look there first. The existing content looks fairly well structured, so hopefully it could be migrated with reasonable effort as a starting point, and any new/reorganised material to fit whatever new IA results from this exercise could then take full advantage. As HTML5 becomes more widespread, I suspect we’ll see both search engines and browsers take advantage of these outlines, just as search engines today have started to recognise site maps and present some results accordingly, so I think it makes sense to follow the presumptive standards unless there’s an obvious reason not to.

Given a clear outline one way or another, you could also do a lot to improve on the narrow, statically positioned tree on the left of each documentation page. That sort of navigation was probably sensible with the browsers and screen resolutions of the time when the current design was put together. Today, it wouldn’t be rocket science to use a wider nav area to take advantage of widescreen displays, and to have it fixed so it doesn’t disappear as you scroll down the page. You could provide some combination of top-level site navigation and navigating a possibly collapsible outline of the current page. However, perhaps you could also provide tools like navigating through search results as a separate list of excerpts like a SERP and/or by making the outline smart about say expanding and highlighting relevant sections when you first open the page. You could probably even do things like providing quick context-sensitive help for main page content, just as we use various interactive features to explore our code in editors/IDEs without leaving our current context.

This sounds like a fun project to work on. I’m almost sad that I don’t have a spare team and a half-year of free time to have a go! I certainly wish the organisers luck and hope a good development team lands the job.

As one of the people behind this, and a PSF director I am here to answer any questions people might have.

A question, out of curiosity and not hostile in any way: what's wrong with the current one?

http://grokcode.com/746/dear-python-why-are-you-so-ugly/

See: http://pythonorg-redesign.readthedocs.org/en/latest/#purpose and http://pythonorg-redesign.readthedocs.org/en/latest/#current... - we outlined, as unbiased as possible, what we feel is fundamentally broken with the existing site.

Indeed, I just read that, so I will follow up further. Is this predicated on feedback you've received or more on what the board feels is appropriate?

Both, actually - we have some real designers on the team to help examine submissions, as well as people versed in IA/UX and accessibility. We (the board) have gotten lots of feedback over the years, and really want to make something more accessible, welcoming and modern.

The team vetting the designs is not 100% board members, intentionally so - as I said, we have domain experts as well as psf members, it's a small team to keep the noise down, but the goals and thoughts are outlined in the RFP as much as possible.

"we have some real designers on the team"

Problem solved!

Well, not really :) There's a difference between having designers, accessibility pros and others able to review the proposals and those that have the time to do the work. All of us are volunteers, and our time is limited.

I'm currently "in charge" of posting most of the PSF related updates, like meeting minutes and resolutions. It's only a once-a-month thing, but it's a huge pain in the ass. To do this, I hop over to my SVN checkout of the site, make a change, build it locally, then `svn ci` my changes and hope they build on the real site and hope we both have the same versions of everything.

I'm currently writing up a doc for a non-techie to take over that task and the steps to go from a clean machine to a functioning system that can make even simple typo fixes are barbaric.

Edit: now I'm at -3. Still, I'm going to let this ride (not delete it), as even though it is not about the web site, I think my suggestion is serious and would benefit Python - i.e. get to the right audience here.

I will also add that Python is my favorite language, and I hold it in a completely separate league from every other language I'm familiar with. Nothing else comes close.

That said.

"Python.org Redesign Request for Proposals"

I was initially excited about the title - due to misinterpreting what 'redesign proposal' might read. I was awed as I started reading the first half of the first sentence of the linked article

"The Python Software Foundation (PSF) is accepting proposals

WOW

for architecture,

WOW

design, development, and maintenance

WOW

...of the primary web site.

Oh.

I really thought you were reaching out the community, really talking about the fundamental design of Python (how I misconstrued the HN title) even from people totally outside of python, in an unprecedented move.

I thought you were really setting out to evaluate fundamental design decisions, that might eventually lead to a Python 5.0 that lives on the web and is attractive to whole swathes of novice and advanced developers who currently use PHP. I think such a widely advertised call for design proposals would benefit everyone.

The websight redesign reachout is, of course, not really connected with such a thought.

A redesign of the Python core language will not convert PHP users. Python is already much better than the PHP language. The benefit of PHP is that it is widely supported by hosting providers and because the default mode of web development (add some php tags to a html page) is extremely easy to get started with.

I think 'hosting providers' are a throwback to the late 90's and the last decade. These days anyone who needs more than a service like wordpress (and there are many, many people who are happy to use hosted blogging etc servies) is likely to have their own server instance. Are there really that many people who have access to 'only' PHP, but not whatever framework they would like? (from django to rails).

I think you underestimate the usefulness of a hosted environment. I need a really good reason to set up a full stack myself and incur the maintenance problems of system upgrades and hardening an entire OS.

That said, you are right that there are plenty of hosting providers with ruby/python available in some capacity.

In the comment that you're replying to, my exact words were "are there really that many people who have access to 'only' PHP, but not whatever framework they would like? (from django to rails)". After I said that loads of people are happy with Wordpress, and other similar services, including with plugins, and just use that instead of php and html.

So, whereas previously (in the 90s) you would have a big jump from HTML only with maybe PHP or you jump up to paying for a server every month and having to lock it down and administer it yourself, now, the former category has access to loads more 'hosted' service possibilities so that what you can do with "wordpress only" has substantially increased; meanwhile, the latter category has come down substantially, due to instances on the cloud being so much cheaper and the amount of uptake making it much more worth it for a company to put out a standardized image with a few frameworks, etc.

So my point was twofold. Firstly, the old 'hosted content' users have access (and use) substantially fuller services, and the old 'full stack' users AND some of the old 'php is all I can use' users now have EASY access to a full instance or whatever framework you want.

Between the two, I think your comment doesn't have much currency.

IMO periodic website redesign and cleanup is a good idea as it does make it easier for users to find information and gives a comforting feeling of a professional look to new users.

THe best way for people to contribute to Python the language is to take a look at the devguide http://docs.python.org/devguide/ and if they're new, join the core mentorship list: http://pythonmentors.com/

I'm saying that you need to broaden your input so that the people who would look at the devguide aren't the only people you're hearing from. Python can approach a local maximum that way, but the things that would make it truly awesome and attractive to web developers would be too out of the box for someone to think of like that. I'm saying, ask everyone, the whole community.

This is why we had a Web Dev summit at PyCon US 2012: https://us.pycon.org/2012/community/WebDevSummit/ - to discuss what we can do as a language and community to make it more "attractive" and ease the on-ramp for the web community as a whole.

So, other efforts are under way for this, and orthogonal to the current RFP

I agree with you on the orthogonality, and wish you luck in getting a very wide base of feedback.

I think Python could be the best language for the web and for any programming anywhere: in the future, if it lives up to its potential, there will be a time when no one should even consider learning anything else as a first or only language. But, for a web developer, I don't think that time is now.

I hope you take fundamental redesigns very seriously moving forward. Good luck.

"that lives on the web"

What does that even mean?

This is a good question. I don't know what the answer is, but there's a good chance http response objects aren't it.

Protip - complaining about your karma just makes people want to downvote you even more.

Resist complaining about being downmodded. It never does any good, and it makes boring reading. [1]

1. http://ycombinator.com/newsguidelines.html

duly noted, and I've edited and removed where I still could. Thanks.

Am I correct in believing that the scope of these documentation proposals is limited to the python standard library and runtime, and does not include the Python package index?

The RFP covers the design (UI/UX/IA) of the Python.org site and back end workflows. PyPI is a separate application in the whole site, and so it's back end code will not change, but it will probably adopt the new CSS/Style

One other thing they should improve is the search function in the documentation:

http://docs.python.org/

The first relevant result for searching "string concatenation" is around the 20th place.

http://docs.python.org/search.html?q=string+concatenation

Funny -- I've used Python and its online docs for many years and never used their search, I always use Google. :-) Google search with site:docs.python.org does a somewhat better job: http://www.google.com/#hl=en&sclient=psy-ab&q=string...

Part of the problem is the use of Sphinx and its search engine (at least this was the case a year ago), where searching happens client-side in JavaScript. This limits how complex the search engine can be, before it is to slow or require to much data to download. Last time I looked it had a simple inverse index with a Porter stemmer and limited ranking of results.

This is great for documentation of most projects as it can be supported with only html+css+js, without a need for a web framework and hosting. But for the documentation of a major programming language I think something more advanced is expected.

The documentation for Python is mediocre at best, which is a wart of how documenting Python works. I think the newer Sphynx site is actually a regression from what they had in the Python 2.5 days.

Best of luck with the redesign. I recently started learning Python and finally realize what I've been missing for so many years.

I'm not sure of the intended audience of python.org (new users vs. experienced), but as a brand new Python user, the current website is filled with lots of great information, but is a bit intimidating. I think the Python language really sells itself and it would be nice to see some simple examples on the homepage as is done on the NodeJS page (e.g. http://nodejs.org/).

Reading through some of the posts on Guido van Rossum's blog was also very inspiring ("Python in the Scientific World", "The depth and breadth of Python"). It's great to see a BDFL so actively involved. There are so many great stories about how Python is used successfully across in so many industries and among well-known brands. It would be great to see more of this on the main page.

we actually put a lot of thought into the target audiences: http://pythonorg-redesign.readthedocs.org/en/latest/#audienc... - and I concur, a frontpage without a language example, or slide show of examples is almost a non starter for me

Excellent -- the "Potential users" summary fits me perfectly. Great work on the rfp. If you need any perspectives or feedback from a very new Python user as you move on in the process, feel free to send me a message. I would be more than willing help.

The current python.org homepage is a mess geared towards developers that already know Python. Compare that with ruby-lang.org and nodejs.org, which both seem geared towards promoting adoption of the language by newbs. They're organised with a clear information hierarchy that makes it easy to find the download button, get started on tutorials and find docs.

Python.org, on the other hand is a jumble of text. The download section is hard to find. The boxes in the right column are more prominent than the boxes in the left column, even though the content of the left column is arguably more important. The middle section is dominated by news that is, for all intents and purposes, worthless to me. There is no visual separation between when the description stops and the news section starts. Unlike nodejs.org, there is no shout-out to companies that are using Python or popular Python libraries, etc. The homepage needs to answer the 5 W's: who is using Python, what is Python, where can I download it, when is the next release, and why should I learn Python? And don't forgot how: How can I get started?

This is basic information design.

I'm wondering if it's really a good idea to have such wildly differing requirements be fulfilled with one just proposal.

Let me elaborate: you're asking a potential bidder to be fluent in information architecture, and back-end development, and systems architecture, and design. Those four disciplines are so far apart that I would be very curious to see if you can select one company that does all of them equally well. And if you do happen to find one, it would be interesting to see if they really can deliver top-notch quality in all of them.

If you ask me, you'd be better of recruiting a separate design, possibly accompanied with an appropriate information architecture, and then start to think about how to do the back-end development and systems architecture.

Not only is this a separation of concerns (hooray!), I also think it will get you a bigger pool of applicants, they will also be more likely to be world class in their field. No-one is world class in all those fields at the same time, and trying to find one company that is will most likely get you an 'average' result in at least one area.

Thank you - I don't disagree with you, honestly though, the overhead of trying to manage those separate entities will quickly outstrip the time and ability the volunteers who are evaluating and managing this process have.

If a given company feels it is lacking in any single area, I encourage them to include other specialists in that area as part of their bid - for example, if they're awesome back end designers, but can not do front-end design, I would expect them to find a trusted designer to work with them as part of the bid.

Even though this effort is funded, the management of it, the evaluation of the designs/etc is all volunteer based. We can not chase multiple contractors :(

That said, the design people/firms I spoke to about this seemed to understand this and stated they would do as I outlined above.

> Content must be editable offline, when there is no network availability.

I'm curious to know why this is a requirement for python.org? I mean, edit contention is an area one has to deal with even if editing with a network connection, so there isn't an enormous technical burden associated with offline editing, but this does require more effort.

Many site contributors prefer offline editing - such as checking out a repo and performing the work, then submitting to online editing. Additionally, the workflow of certain sub sites, such as the jobs board require a fair amount of offline vetting prior to content going live.

Essentially, we have to serve two styles of workflow - we have both types of people wanting to contribute content today, and we are attempting to fulfill their workflow needs. A 100% online CMS does not do that.

I'd guess that there are current website editors (especially writing docs) whose existing workflows include a lot of offline time. Poor Internet connections at home, lots of time traveling and working on airplanes, vacations to beautiful places with no Internet...

Yup, exactly.

I don't mean to hijack the thread, but (a bit) relevant: https://groups.google.com/forum/#!topic/django-developers/2X... "Redesign of djangoproject.com"

good luck for both, can't wait.

The Python website certainly doesn't have a welcoming feel to it.

A redesign will be a great move.

Strongly disagree. The python website has always felt like one of the last bastions of function over form; it's not slick, but the content you actually want is right there without any distractions. If it turns into one of these 30%-margin, rounded-corners sites with half the text I'll be sad.

Maybe I'm just getting old.

This is definitely a shameless plug, but I thought it might be worth mentioning here that my current side project is a MIT-licensed Python documentation API called "Python Docs," available at: http://github.com/mvanveen/docs .

The goal is to leverage static analysis as much as possible to provide an intuitive API for Python documentation primitives. So far I have used the project to power a code browsing interface that I recently started working on, but I think that others could find the project really useful.

Plone should do something for this, it sounds very well suited? Any plone people about? I guess moinmoin/trac too :) What about some Django or pyramid teams?

People from the PSF will probably also put in a proposal, since lots are web people. Which ones?

A top agency could probably charge at least $1 million for something like this. So I doubt there will be a top result... unless they do it pro bono. Which would let USA companies do it as a tax right off if I'm not mistaken? Maybe one of the sponsors will put in a bid: Facebook, Google, or Dropbox?

All very exciting.

Or perhaps some wunderkid-wizard-wonk will hack tirelessly on their keyboard+wacom - powered only by a will to provide pythonistas everywhere a great website. They will about face everything with a fresh open approach, that turns the ideas upside down and puts code and projects first, doing an edgy remix of pypi, that integrates an IDE console inside the website (or coming up with an actual good idea) that makes people think "why weren't all programming websites like this already?". They'll do all this before the submission period is even up, having gathered feedback and evolved their idea consulting tens of 1000s of pythonists, djangonaughts, and people from other communities. Time magazine will have a picture of them next to the new python.org with the headline in all caps... "EPIC".

Looking at the requirements, particularly l10n and the REST API for editing (which rules out compilers, unless the API server operates at a different privilege level), this will have to be solved by something like a CMS. Except for the offline editing requirement, which makes something DVCS-backed necessary. Anyway, it will be a good showcase for whichever stack is chosen.

In something as complicated and as has as much information as a an open source project does, the need for a clean, organized, thoughtful interface plan/design is paramount. The quicker the information is to find and the more digestible it is, the quicker the project will be adopted and built upon... in theory of course!

Might this include some improvements to the dreadfully designed Sphinx?

Sphinx is a project of it's own.

The RFP says "The proposal may feature a retheming of http://docs.python.org but need not do so," so that depends on how ambitious the proposers are. The focus of the RFP is definitely www.python.org.

Good luck!

Yeah, we'll need it - it's been a long time in coming.

Reply on news.ycombinator.com