102

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.

3
  • 14
    I numbered the items so that it will be easier to address each one. I think these are valid concerns, but we aren't quite ready to address them. I'll give my full thoughts in an answer.
    – Jon Ericson Staff
    Commented Dec 24, 2016 at 20:21
  • I don't know how relevant #2 is, as people experienced in one technology will sometimes post a question looking for an equivalent feature in another technology. With a one-point minimum, I would be able to approve edits to 45 tags with which I have experience ranging from "just started learning it a couple days ago" to "I have no memory of this place." Commented Dec 27, 2016 at 4:22
  • 4
    @TigerhawkT3, I know that the one-point minimum isn't perfect, but in my mind there needs to be a starting point somewhere.
    – auden
    Commented Dec 27, 2016 at 14:20

1 Answer 1

29

This is very helpful feedback. Let me take the items one-by-one:

  1. I left a comment to another question:

    I've been envying the Wikipedia Main Page a lot lately and not just for Docs. It seems to me the endless, unstoppable stream of questions serves mostly to remind us that there is an endless, unstoppable stream of questions. It would really be lovely to give browsers (as opposed to people arriving via search) something more engaging. It also seems very doable in a short period of time.

    It would be handy if Stack Overflow's main page showed content that we think you are likely to be interested in. So for you, that might mean more LaTeX and Python questions and topics. In fact, we already have something along those lines if you use the Stack Exchange app:

    enter image description here

    In the short term, the easiest fix for the Documentation home page would be to honor favorite and ignored tags. Favorite tags could be put in the front of the list and ignored tags shuttled to the end.

  2. I don't like the idea of restricting reviewers by tag. While it's true some people don't know enough to review outside of particular tags, other people have broad knowledge that might not be reflected in their answers. You can chose to filter by a subset of tags, if you like:

    enter image description here

    But this feature isn't obvious or on by default, so many people don't get the tags they are most interested in. I think that's something we can fix, but I haven't yet talked to a developer about potential technical limitations.

  3. I agree that we need more "Documentation milestones". We can certainly add more badges, but we really want to be sure that Documentation is working before we do so. The specific thing you mentioned, an indication of how much weight your review has, is a bit tricky since it depends on whether you have a silver tag badge for the topic's tag. I suppose we could note that on the review itself, but I share Shog's philosophical concern about making binding votes obvious. People should vote as if their vote were binding even if the system doesn't trust you enough quite yet.

  4. Shortly before launch, tags didn't have a topic list tab. Instead, you needed to navigate to topics via the dashboard. This was a conscious decision, because we wanted people focus on content creation and not browsing. It's also our belief that eventually most traffic to topics will come via search, just as it is on Q&A. However, during usability testing we learned that people want to see examples of what people have already written before contributing their own content. (Yeah, I was shocked too. ;-) So we added the topic list tab, made it the default, ran another round of tests and figured we were ready for launch. It worked sort of all right when you have a handful of topics, but it's not great for lots of topics. Worse yet, we don't have the best native search quite yet.

    So there's certainly a problem. We have an item to address it in our backlog, but it's not yet a high priority. Helping people find excellent content is going to be a priority soon, but we'll probably explore the search and crosslinking vectors first. (I really like your map idea, however. I'm going to keep that in mind.)

  5. We also have an item in the backlog for better profile integration. As with #1 and #4, fixing the dashboard is something we'll need to do, but we aren't quite ready to tackle it at the moment.

  6. I'm not entirely sure what you mean by dragging examples around, but examples are currently sorted by votes and one may be pinned. We discussed allowing more options to manually sort examples, but we decided the extra complexity wasn't worthwhile. That's a decision we might reconsider.

    I'm also not sure about the search and share suggestion, but you can get a link to an individual example:

    Share icon
    Share link

    Is that what you were looking for?

  7. I agree about voting! You do get +2 for each accepted proposed change, so that's something.

4
  • 11
    #6, I meant the ordering of examples. I don't think ordering by votes always makes sense - for example, I wrote a whole topic on formatting math equations in LaTeX. I don't want my example on matrices before my example on the very basics. For part two of #6, I meant how in Wikipedia, you can highlight text, click the link button, and it automatically searches among already existent Wikipedia pages to link too. In other words, it is currently possible, with the link you mention, but it requires a lot of extra work. Hope that makes sense!
    – auden
    Commented Dec 24, 2016 at 22:14
  • 4
    Another small suggestion: I love the favorited/ignored tag thing, that's one of the main things I was hoping for for the documentation page. However, if a user has no favorited/ignored tags, I might suggest sorting the topics by type; i.e, web development, or whatever, and then within that by popularity.
    – auden
    Commented Dec 24, 2016 at 22:17
  • 8
    For #2, I think it would probably be best if it defaults to filtering by a user's most active tags, clealy describes how to change filters, and remembers preferences. That way, it basically makes reviewing content you're not entirely familiar with opt-in, which will likely result in people that aren't as good at reviewing unfamiliar languages sticking to the ones they know enough about to review fairly. Commented Dec 26, 2016 at 7:39
  • 1
    Increase it from +2 to a little bit more, esp. for significant edits. The slow trickle of +1 is not enough. Commented Dec 27, 2016 at 2:29

Not the answer you're looking for? Browse other questions tagged .