Docs issue tracker

Okay, so the preliminary version of the Docs Issue Tracker is up. Here’s a quick rundown on how it works.

Note: I fully expect it to be slightly buggy at first. 🙂

The issue list can be seen at . You will need to be logged in and also an editor on this make-site to do anything useful here. The dropdown menu on the right is the action menu. You can “accept” an issue, “close” an issue, or “reopen” a closed issue. Again, preliminary, this can be expanded later if needed.

Issue submission can be done at . You will need to be logged in, and when you visit this page, it will force you to do so if you’re not already.

However, it will be the case that we link to this page from other places on the website. I put a link on my Codex page so you can see how this works:

When you click to that submit form from somewhere else, it auto-grabs where you linked here from, and fills in the URLURL A specific web address of a website or web page on the Internet, such as a website’s URL of the problem. There is some sanity and safety checking here, so it won’t work for all links from everywhere. Also note that the link to /issue/submit should always be httpsHTTPS HTTPS is an acronym for Hyper Text Transfer Protocol Secure. HTTPS is the secure version of HTTP, the protocol over which data is sent between your browser and the website that you are connected to. The 'S' at the end of HTTPS stands for 'Secure'. It means all communications between your browser and the website are encrypted. This is especially helpful for protecting sensitive data like banking information., because of referer restrictions when going from https sites to non-https sites. Based on the URL, the location information on the ticket is filled in and so forth.

I know it’s not quite the prettiest. Sorry. HTMLHTML HTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites./CSSCSS CSS is an acronym for cascading style sheets. This is what controls the design or look and feel of a site. suggestions are welcome. Also, pagination is there, just not displayed until there’s more issues. Currently it’s the default of ten per page, I’ll increase that eventually.

Things missing:

  • Stats
  • Re-ordering by status
  • Probably some other stuff

Again, this is a starting point. Things can be added to it, as needed.

Also, please don’t add “test” issues. I’ll do the testing. If you have real issues, feel free to add those. 🙂


Types of Issues for the Issue Tracker?

Happy Friday Docs Team!

We’re getting closer and closer to having a working issue tracker! One of the open questions is what “types” (or categories) of issues you want to track. In the mockups, we used placeholders like “spelling mistake” and “grammatical error,” but these were just placeholders for the mockups.

So what “types” of issues would you like to track? How would you like to organize your issue tracker?


Docs Issue Tracker Mockups

Happy Monday Docs team!

@karmatosed has started plugging away at mockups for your issue tracker and we’re ready for feedback!

First off, here’s a mockup she’s created of the actual tracker itself, which is affectionately codenamed Documentron.

The tracker includes columns for: reported username, date reported, type of issue (we’ll discuss which types are wanted during the implementation phase), current status, a link to the page with the problem, and a button for resolving the issue. It also includes a hide/reveal triangle for seeing the details of a particular issue.


Additionally, here’s a second mockup showing how hover states might work on the tracker.

@karmatosed has also worked on a set of buttons that would be placed on documentation allowing anyone (who’s logged in) to report an issue. Which one do you like most and why? Feel free to discuss the placement of the button as well. We’ll want it somewhere consistent across all docs.



But that’s not all… Once someone clicks to report an issue, where do they go? Assuming they’re logged in, they visit this wonderful form:



Alright Docs team, what do you think about the mockups above? Keep in mind, they’re just mockups right now and might still need some design touch ups. Anything you think of is useful at this stage so we can get the mockups just right prior to sending them to a developer to implement.

Thanks for all your feedback!


Documentation Issue Tracker Spec

Hello Docs team!

Siobhan previously posted about the need for an issue tracker for documentation. Well, as luck should have it, I just published a specification for such an issue tracker! I’d love your feedback on that spec, so we can get started on designing and developing it.

After we reach agreement on the overall spec, I’ll work with you to answer the various open questions listed in the spec, then post here for feedback.

For those of you with design inclination, in the not-too-distant future we’ll need some design work done on both parts of the issue tracker. Volunteers welcome.

Leave your questions and comments here or on the spec itself.


An issue tracker for documentation

We’ve been discussing on-and-off an issue tracker for documentation. We’re reaching the point at which we need to make this happen. This will solve two problems:

  • people want to contribute to docs but don’t have a central list of tasks that they can sit down and tackle
  • more and more contributor days are happening and our issue tracker will be a place where organisers can find tasks for the day

What’s the issue tracker for?
The issue tracker is a central place where people can report issues related to documentation (kind of like tracTrac Trac is the place where contributors create issues for bugs or feature requests much like GitHub., but for docs). Examples:

  • reporting an out-of-date example in the code reference
  • reporting a page in a handbook that needs copy-edited
  • reporting a page of content that hasn’t been updated to the latest WordPress version

Essentially, it’s for bugs with documentation.

How would it work?

A person is working with the documentation and wants to report an issue. We provide a place for them to do this, with an appropriate tag applied to the report. This could even be built into documentation pages so that they don’t have to leave the page they’re on.

The report would go into the tracker, which would generate a list of issues (at make/docs/issues, for example). These would be tagged and an interested person could click the tag to bring up a list of issues for that tag.

Or, it doesn’t need to be done that way but that’s how it is in my head.

If anyone has any suggestions on how we could implement this please let me know in the comments.