Verbatims
The table below lists the raw comments from participants at the Berlin (Feb. 8 & 9) and San Francisco (Feb. 23) doc sprints, and tracks the bugs logged against these issues. The gathering of this information, along with the survey was the first effort toward gaining insight into the usability of the wiki for contributors. Herein are summarized the findings with a bias toward raising issues with respect to editing and contributing.
Summary
The verbatim information below is summarized here by category. Not all categories are summarized.
Design/Layout
- Broken, unimplemented features (Comments, Q&A) are confusing users.
- Users are unable to log in because the log-in elements do not appear on the home page.
Editing tasks
- Editing in MediaWiki and with SMW forms is not easy (this runs contrary to one of our basic assumptions)
- Session bugs are a serious impediment to productivity.
- Need a guide to creating examples.
- Need a process (and a flag) for reviewing contributions.
- Topics and topic clusters are confusing and rife with abuse.
- How to documentation (WPD/*) is hard to find and difficult to follow.
- Markdown is preferred over MediaWiki markup.
- Flag design is scaring some users away from working on pages.
Forms
- Syntax section too restrictive, not applicable to all cases.
- (Many other issues, see below.)
Getting Started
- Need to identify tasks according to role, domain expertise, skill.
- Need tasks for designers, and others.
- Supplement the Getting Started pages with video.
- Need a more obvious path to getting started from home pages.
Search
- Duplicate pages in search results - one for each instance of the search term (this is low-hanging; why is it still on the tree?)
- Can’t search internal help pages.
Next steps
To help with the resolutions to these problems, in the list below cite the relevant bug from our project management system. If the issue requires a new bug, please create it.
Issues cited by doc sprint participants
| Bug | Category | Issue |
|---|---|---|
. |
Content | Examples do not show best practice |
. |
Content | Examples contain irrelevant information |
. |
Content | Reach out to authors of NetMag, Smashing Mag, etc. to ask them to contribute published articles |
. |
CSS project | Not clear where property belongs (Length: CSSOM or CSS?) |
. |
CSS project | No way to identify which CSS properties are already taken for tasks |
. |
CSS Project | CSS properties marked as non-exist (background) which actually do (not under /css but under /css/cssom) |
. |
CSS Project | Don't sort the content based on the browser's code implementation, but think about users. A web developer doesn't care if context.font belongs to canvas.2dcontext, he or she will search for a `working with fonts` section |
. |
Design/Layout | "Block of editorial notes" styling needs improvement - it currently just appears at the top of the page like normal text. This styling is terrible. Surely this should be put in a different style that makes it look obvious that it is not part of the article … or hidden behind a open/close box, or something. Maybe even put it on the discussion page? Get those back up and working? |
. |
Design/Layout | The comment speech bubbles are no longer showing, and instead you get a messy bit of text shown, which looks bad. |
. |
Design/Layout | I cant add answers to the q/a section. Dont know why, everytime the page says i am not logged in. Pipe issue is an issue. |
. |
Design/Layout | Login on the front page |
. |
Editing tasks | We should define a schema for creating examples - making them consistent |
. |
Editing tasks | Review by someone with greater familiarity/expertise (could watch pages and check as they are saved) |
. |
Editing tasks | Editor identifies pages that requrire further review for escalation (via comments, flag tech review required, urgency) |
. |
Editing tasks | Identify content in terms of % completeness |
. |
Editing tasks | Missing instruction on how to edit compatibility tables |
. |
Editing tasks | Need a flag: "Review Required" |
. |
Editing tasks | [good] Forms identify content chunks for the purpose of querying |
. |
Editing tasks | Domain knowledge required for "Topics" vs. "Topic Clusters" (knee-jerk solution, documentation, not going to solve the problem - nobody reads) |
. |
Editing tasks | Make it easy; the forms and other mechanisms are not sufficiently easy to work with |
. |
Editing tasks | Video task: creating api pages, CSS properties, getting started tasks |
. |
Editing tasks | Using SMW forms, with all the checkboxes, fields is really annoying, significant hurdle to editing; prefer Kuma model - single page, no templates, no forms |
. |
Editing tasks | Stability or Bug Fixing. When Saving a CSS property page, some of the contents is not saved unless in prior one clicked "preview". The time it takes to make even small edits is far too long. Also textfields of templates are far too small to get all the content in conveniently |
. |
Editing tasks | clearer documentation |
. |
Editing tasks | don't restrict edits or mark them as non-editable |
. |
Editing tasks | improve editing by changing syntax to Markdown or HTML |
. |
Editing tasks | The site needs more speed and there are a lot of little bugs and showstoppers that slow you down a bit. It is also not clear what to do with imported but unfinished content, and how to contact authors of content with disputable quality (e.g. a11y parts) |
. |
Editing tasks | Workflow, versioning, reviewing. |
. |
Editing tasks | Although flags are useful, maybe find a way to explain a bit more what needs to be changed or improved, and how. |
. |
Editing tasks | When we are done with editing, maybe a special state "needs review", before removing old (addressed?) flags. |
. |
Editing tasks | A "being-worked" state to prevent conflicts ? |
. |
Editing tasks | Switch from mediawiki syntax to smth. devs are used to know (markdown) |
. |
Editing tasks | Solve the session timeout issue, introduce a Markdown editor, implement a mediawiki extension that converts characters into html entities. It would be awesome to have the form organized into steps, so one can fill them out one at the time quickly and easily. |
. |
Editing tasks | Get rid of Mediawiki. Seriously. |
. |
Editing tasks | Bug fixing (Session bug et al), finally, and as thoroughly as possible. This is the perfect showstopper to turn away anybody that has had interest (and these people might not come back that early). |
. |
Editing tasks | "Topic's incomplete" flag is scary. Is this good? |
. |
Editing tasks | make priorization (= need of review) online |
. |
Forms | The "syntax" on the CSS properties template (and probably others too) is not strictly speaking syntax, it is more usage or examples. Syntax implies proper syntax notation like you'd see in the specs. Should we show both? Should we change the labelling of the current "syntax" to something else? |
. |
Forms | in examples blocks, the system should escape HTML automatically. It is stupid having to escape it yourself with entities, etc. |
. |
Forms | The title you put in the "custom page title" field should be used in the breadcrumb trail, but it isn't - this should be fixed |
. |
Forms | Why Java syntax in a CSS property page? |
. |
Forms | Not clear how to edit compatibility tables. |
. |
Forms | Need a form for "constructor method" in APIs |
. |
Forms | Required forms should always be visible; hide those that are optional |
. |
Forms | Please improve input boxes and stuff like this |
. |
Forms | The editing of content is really hard. The Templates are not really explained and you need to search for answers. Example pages with all templates would help alot! |
. |
Forms | The MediaWiki bugs regarding examples and such (where sometimes code was rendered and sometimes not) were a bit annoying. |
. |
Forms | Define clear and useful structures and rules for the entries |
. |
Forms | In other words: the content pages are aready nice and useful, the structure to get to these pages is horrible (atm) |
. |
Forms | Related links should be ordered from general and introduction down to more specific, and there should be a method of labeling what was a tutorial, video, example, etc. |
. |
Getting Started | Identify different levels of expertise required for editing pages - skill level required |
. |
Getting Started | Identify tasks based on expertise, skill level required. |
. |
Getting Started | Identify tasks appropriate to role: developer vs. noob vs. designer |
. |
Getting Started | Identify tasks appropriate to domain expertise |
. |
Getting Started | Identify the value (learning) of the trivial "cut-n-paste" as being separating the "implementing" pieces from the "developing" pieces |
. |
Getting Started | Set the expectation that the "trivial" task will teach the object model so that contributors can graduate to higher level tutorials, concepts |
. |
Getting Started | Time considerations are irrelevant to the completion of tasks, either a contributor can or cannot complete the task - based on domain knowledge, skills |
. |
Getting Started | It would be nice for beginners if small tasks were grouped by task somewhere and listed on a small list just to give an idea how to participate. It doesn't need to give every possibility. |
. |
Getting Started | how to contribute to UX and visual design, for non-technical people |
. |
Getting Started | improve presentation of tasks list |
. |
Getting Started | Home page needs a link to New to WPD--Beginners Guide should be on the home page How about a video for the very new to the site |
. |
Getting Started | Was not totally obvious where to find the "To Do" List... Getting Started should be Boldly Highlighted... |
. |
Getting Started | Was not easy to hone in on the Specific Task assigned. Not clear whether this was a 5 minute, half-hour, etc. Should have a more specific list of Types of Tasks... |
. |
IRC | Ambiguity unresolved between #webplatform vs. #webplatform-site - not everyone clear on which to use when |
. |
Registration | User agreement needs summaries: open license, attribution, bullet points on what they are agreeing to. |
. |
Registration | User didn't know about "Confirming their WebPlatform Account" which would have enable Editing. Indeed, she checked her Email and confirmed. |
. |
Search | Some people want to just look at site compatibility info, or code examples. It would be nice to create the site in a way that people can search to just bring up site compat info or code examples, and not have to trawl through all the full reference pages. |
. |
Search | search gives me the same page several times, if the word exists several times - that wierd. |
. |
Search | Make the search function outputting useful content. |
. |
Search | searched for "Responsive Design", ambiguous results |
. |
Search | Can't search internal help pages. |
. |
Search | Performed a site search for "topic clusters". No hits found. |
. |
Templates | Open templates to editors, run chron job to check template usage, report out to community |