Skip to main content
3 of 3
Copy edited (e.g. ref. <http://en.wikipedia.org/wiki/Python_%28programming_language%29>). Expanded.
Peter Mortensen
  • 31.6k
  • 4
  • 22
  • 14

The things that drive me nuts about documentation

These are some of the things that make me wince every time I enter the documentation side of the site, that I think a decent number of people would agree with. I'd like to see what people think about this, of course, but not only do I list problems, I try to list possible solutions, so this is a bit of a feature request.

  1. The opening page of documentation drives me nuts, to be honest. It doesn't look too terrible, but what if (like me) you contribute to a corner of documentation that isn't at the top of the popularity list? Then you have to click over to the search bar, type it in, press Enter...in short, you have to work to get to the page. My suggestion? Allow users to see several different fields - popular documentation (like votes over on the main Stack Overflow), documentation recently viewed by you, documentation recently changed (like newest and active combined over on Stack Overflow), and favorited documentation. Yes, favorited documentation - please, allow us to star language documentation and documentation pages like we can favorite tags and questions.
  2. Review - why am I, someone who knows nothing about practically every language except Python and LaTeX, allowed to approve or disapprove edits across the entire range of tags? This makes no sense. Please, restrict this by saying there must be at least one upvote in a particular tag, at the very least.
  3. Review #2 - also, it isn't clear how much reputation you must have to have an edit just approved instead of reviewed - maybe this could be made clear somewhere? For that matter, it'd be nice to have a list of documentation "milestones".
  4. The main page for each individual topic. Instead of a long list, I'd suggest having a page like the active page over on Stack Overflow, with updates, and a page which has the documentation pages arranged kind of like a web, showing where the different topics connect, and starting with an installation guide, or something of the sort.
  5. The dashboard as a tab at the top makes things kind of confusing. It'd be nice if instead this was added as a tab to everyone's profile, with the documentation drafts and everything shown, and then within each topic, the requests could be found as red circles on the web mentioned above, if that makes sense.
  6. Writing the documentation - I can't seem to drag examples around once I've written them, which would be nice. Having a button where you could search documentation and link to the appropriate page would also be kind of nice (like on Wikipedia).
  7. Finally, I would suggest to all documentation users to vote often on anything that helps you or passes your "this is a valid piece of documentation" test. I know it frustrates me to see a few select examples in popular tags with hundreds of upvotes with quieter corners of documentation devoid of votes. Maybe just contributing to documentation and passing review should get you some reputation, I don't know (though of course this couldn't be the case until review is an actual test).

Hope some of these suggestions make sense, and I'd be glad to hear people's feedback on these.

auden
  • 1.2k
  • 1
  • 7
  • 12