Supporting Everything WordPress

Tagged: docs Toggle Comment Threads | Keyboard Shortcuts

  • Drew Jaynes (DrewAPicture) 6:31 pm on January 10, 2013 Permalink | Reply
    Tags: docs, pathways, Support, wptrt   

    Docs is trying to build pathways to support 

    A Twitter discussion this morning spawned a conversation about the lack of breadcrumbs to support in the Codex, namely for theme authors looking to ask questions about the theme review guidelines.

    The Docs team is compiling a list of articles that point out some of the support pathways, such as mailing lists, IRC, the forums or other channels.

    We welcome any input and discussion: http://make.wordpress.org/docs/2013/01/10/missing-breadcrumbs-to-support/

     

    • esmi 11:29 pm on January 10, 2013 Permalink | Reply

      Done – from the perspective of someone who also tends to hang around the theme review list a fair bit. :)

  • Andrea Rennick 10:44 pm on July 26, 2012 Permalink | Reply
    Tags: , docs   

    Codex work 

    We should probably get a conversation going not only about needed Codex work but *how* to approach a better structure and how to get the work done.

    I’m leaning towards a re-org and maybe a bit of a division between users docs and programmer notes. A good example of this the Pages page. It starts out as a user doc then jumps right into code.

    Things like Handbooks need to be sorted out and linked to as well.

    I think if we could sort out the right approach first and focus on specific pages or topics later, then we’d start making big progress. Possible if we even approached it like a WP dev cycle, with clear targets and a deadline.

    Possibly a mentorship program as well, wehre we could round up people to help and start handing out assignments and being there to keep people on task and for any questions they have.

    All thoughts welcome here. :)

     

    • Siobhan 11:08 pm on July 26, 2012 Permalink | Reply

      I would love to be involved in a re-organisation of the Codex. Building documentation projects from the ground up is something I’ve been involved with a lot recently. This is both for documenting new projects from scratch and coming on board when documentation has become a mess and totally reorganising it.

      A division between developer docs and user docs is a great place to start. Users are freaked out by developer stuff, and developers don’t need access to user stuff (at least not when they are developing). I think the WordPress Lessons section of the codex is a great start for user docs but I’m not sure if users are actually going their as their first stopping point for help.

      Something I’ve found immensely useful when thinking about how to restructure documentation is carrying out a content inventory. Basically a spreadsheet with a big list of titles and locations and maybe some comments. For the Codex the thought of this kind of scares me because it’s such a massive beast, but yeah, it’s a really useful exercise.

      On a more general Codex related note, I’ve spoken to a lot of people about the Codex recently. At WordCamp NYC we got people to come along to the hack room and we took over it and talked to people about writing on the codex. We did try to get some writing done but we actually found the learning curve for mediawiki was too difficult to tackle in that sort of environment. i.e. people had to learn mediawiki from scratch + codex styles & conventions, which meant sitting reading stuff when they actually wanted to be practically doing. However, what was heartening, was that so many people came along (I met @zoonini there :) ). There were about 20 people who came in and out, and at least half of those had no idea that you could contribute to WordPress by contributing to the Codex. It’s not really something that people think about.

      At WordCamp UK we did a panel on contributing to WordPress, and almost everyone agreed that the WordPress Codex is the area most in need of some love and attention. I think part of the issue is that people either a) don’t have the time to write technical documentation or b) don’t enjoy it. Also, a major issue that was discussed is that there is nothing on users’ WordPress profiles to acknowledge that they have written in the Codex. So if you write a plugin or theme it’s on your profile, you get props and acknowledgements for contributing to core, support threads appear on your profiles, but there’s nothing about Codex activity (or for translations, I think? and probably other things). So, in some ways it feels like a thankless task. You’re not a “rockstar”, you don’t get “props”, you’re not a mod or anything cool like that. And for a lot of people that doesn’t matter, but for others it does and some form of acknowledgement may encourage more people to get involved. I think there’s something in the works related to this, but am not sure of the details.

      Anyway, +1 codex organisation. I’ll help whatever way I can. I did have other thoughts but it’s gone past midnight so will see what comes to mind again in the morning.

    • Christine 11:30 pm on July 26, 2012 Permalink | Reply

      I’m just going to come out and say it, and I’ll make enemies, I know… but if the folks at Automattic are serious about this, they need to hire someone. The codex needs way too much work to put this in the hands of volunteers.

      I’ve edited a few pages and I was really scared. I’m just not confident enough to put code snippets — which I use all the time — but I’m just not sure if they are used correctly. I only posted my snippets after having asked a couple of people on twitter to confirm that what I was saying was indeed accurate.

      • Ipstenu (Mika Epstein) 1:31 am on July 27, 2012 Permalink | Reply

        I agree about the hiring.

        The code snippets aren’t as important as getting the right information. I mean, we can come up with examples later, but some of that data is downright incorrect :/ I get the fear. MediaWiki is a hefty hungry hippo, but it’s really good.

      • Siobhan 8:49 am on July 27, 2012 Permalink | Reply

        I also agree that someone really needs to be hired to fo it. However, I’m not sure if Automattic is the company do to it. It’s sensible for them to hire people to work on core, ui, even accessibility, as those things affect the core product at WordPress.com, and at WordPress VIP – improving them makes what they have to offer, but the Codex has no effect on their business so investing in a person working on it makes no sense. After all, they have their own docs at wordpress.com (http://en.support.wordpress.com/) so why do they need the Codex?

        Many of the people I spoke to, development shops, businesses using WordPress, even individual freelancers, wanted to find a mechanism to give back to WordPress but couldn’t do it in terms of time. One idea was for groups of people to get together to pay for a dedicated person to work on WordPress (there are companies, like Automattic, who do this) but there are obviously logistics that need to be worked out to do with paying and managing a person.

        For the Codex, specifically, we had the idea of crowd sourcing the funding (using something like Kickstarter) to pay for a person to completely work over and renew the Codex. Where people are often unwilling to give time, they are willing to give money (or to be part of the project and give away something relating to their business). This would mean that the person who actually took the lead on the codex would be community generated, as opposed to coming from Automattic (which anyway is extremely unlikely). Logistically, once enough money was raised, then I have no idea what would happen with it, who would sort out the hiring, or manage the person or whatever – maybe the money could be donated to the Foundation to take someone on.

        Anyway, it’s a bit out there, but I certainly think it would be possible. If Chris Coyier can get $90,000 to screencast his website redesign (http://www.kickstarter.com/projects/150422311/screencasting-a-complete-redesign) then a group of us could probably get double that to pay for someone to work on the Codex for two years, and also pay for any logistical management stuff around that person.

        • Andrea Rennick 11:15 am on July 27, 2012 Permalink | Reply

          Also adding a note here that we do have permission to take whatever we need from the wp.com docs and put it in the codex.

        • Christine 9:16 pm on July 29, 2012 Permalink | Reply

          Good point about Automattic not needing the Codex, I hadn’t thought of that.

      • Andrea Rennick 10:45 am on July 27, 2012 Permalink | Reply

        I can agree to a point, but Automattic is not in charge of wordpress.org. ;)

        Some of the most needed work is for *users* and not code based at all.

        • Lorelle 5:24 pm on August 1, 2012 Permalink | Reply

          Some fantastic suggestions and ideas.

          1. The http://wpdocsteam.wordpress.com/ to do list has an ongoing list of things to do.

          2. The Docs Team Things to Do List also includes ongoing work on a document inventory and cross checking.

          3. Attempts to separate development information from programming (theme/plugin/tweaking) has been ongoing for years and continues to be a critical area of development in the Codex.

          4. I’d really like to see all the international language support pages on the Codex separated in some way so they do not appear in the general Codex or do – with intention and clarity. Right now, the mix of the languages are causing confusion on multiple levels. Wikipedia is doing it by sorting by language code in the URL, and I think that would be smart for us. It would also give polyglots team members a chance to call parts of the Codex their own in translation.

          5. The success of WordPress Support is tied closely with the WordPress Codex, especially now that the two are grouped together here on this site. Thus a hiring a documentation coordinator is a natural idea. It is also natural that they would be hired by the Foundation. It is a community project, little different from WordPress Support and WordCamps.

          6. The person behind the design aspects and database control of the Codex must also step forward or be assigned. There is much that can be fixed with some simple search and replaces (changing WPMU to WPMS – with redirects, too) and design tweaks. I think that visually identifying pages that are developer versus WordPress Lessons versus general documentation would also be sweet.

          I’m thrilled with the work Daniel and others are doing to bring over handbook documentation to the Codex and expanding upon it. I’m delighted that the Codex is getting energy thrown at it after years of lack of attention for a variety of reasons.

          For those that want to jump in NOW, until someone contacts me about porting over the to do list, head to it and tackle something. http://wpdocsteam.wordpress.com/ The list is extensive and action items are right there, and it’s a great way to keep the discussion going on how some of the documentation elements should work and be structured, sticking specifically to articles and not general topics.

          Thanks.

    • esmi 11:57 am on July 27, 2012 Permalink | Reply

      I’d suggest that hiring someone really is the last resort. The problem with documentation is that everyone assumes someone else is doing it. Unless of course they come across a gap when they needed info, do the research and have the community spirit to take time out to add the missing documentation.

      I’d argue that some of the user-focussed could (should?) be initially handled by the UI and Dev teams. If a new feature is added to the UI, then surely the UI team should ensure that there’s a basic page explaining how to use it? Once there’s something in place, I think you’re more likely to get random people updating/improving it. Creating a brand new Codex page is a far more daunting task (from a confidence pov) than editing an existing one.

      • Andrea Rennick 12:09 pm on July 27, 2012 Permalink | Reply

        When they add new features, someone does usually make sure a new page gets added.

    • esmi 12:01 pm on July 27, 2012 Permalink | Reply

      +1. A separation of user v. coder documentation is a great idea. Could a top level split into 2 distinct streams be a practical option?

      • Andrea Rennick 12:09 pm on July 27, 2012 Permalink | Reply

        That’s what I’m leaning towards. Maybe the front page be even more simplified into User / Dev much like we have splash pages here with English / French.

    • Thomas Scholz 11:30 am on July 28, 2012 Permalink | Reply

      The Codes lacks gamification. Give contributors some public visible feedback on their profile, and they will come. Maybe a golden badge for 1000 unreversed edits or something similar.

      • Thomas Scholz 11:30 am on July 28, 2012 Permalink | Reply

        Errm Codex. With X. (:

      • andrea_r 8:47 pm on July 31, 2012 Permalink | Reply

        Been discussed before in different contexts (contributions, etc) and shot down.

        • Thomas Scholz 1:32 pm on August 3, 2012 Permalink | Reply

          Sad. I strongly recommend to reconsider that.

          • Ipstenu (Mika Epstein) 3:11 pm on August 3, 2012 Permalink | Reply

            The feeling has generally been that if you’re going to help, you’re going to help, and what are, essentially, meaningless rewards like ‘karma points’ won’t help. While we all help for our own reasons, the fact that we do it for no rewards is a powerful factor in our work. We do these things to make WP better and to learn :) Pretty awesome, IMO.

            • Thomas Scholz 11:00 pm on August 4, 2012 Permalink

              I agree, the main motivation should not be bound to a reward. But it might work better with some gamification – I have seen this in other places, and I think it is worth an experiment.

    • Daniel Bachhuber 12:48 am on July 31, 2012 Permalink | Reply

      Howdy! I work on Automattic’s WordPress.com VIP team and I’d love to contribute to Codex efforts on a regular basis. We sometimes often receive complaints about the lack of quality technical documentation — it seems like the Codex is the best place for that.

      Here’s one piece I’ve already ported over from our internal documentation.

      There are a couple feature requests I have to make the Codex more useful:

      • Email notifications for changes on pages I’m watching
      • An API (with corresponding WordPress plugin) so I can make Codex documentation embeddable in other sites.

      Other than that, I’m happy to help out with the more complex technical documentation — it’d be great to have a bit of help figuring out what is needed.

      • Ipstenu (Mika Epstein) 3:52 pm on August 2, 2012 Permalink | Reply

        Email notification doesn’t come with MediaWiki (boo). RSS does, though.

        API… Didn’t @rarst have something? I don’t think anything is APId like that by default for MediaWiki.

    • coffeemanmatt 3:27 pm on August 2, 2012 Permalink | Reply

      Hi all – along with Daniel, I also work at Automattic, but I’m on the Happiness team.

      Part of my job is to maintain the WordPress.com support docs, and I’m *very* interested in helping out however I can with the Codex. After all, WordPress is WordPress.

      • Ipstenu (Mika Epstein) 3:51 pm on August 2, 2012 Permalink | Reply

        Y’know… most of the time, the info on the .com pages can be lifted wholesale to .org, with only a couple tweaks. And I know Matt already said we were allowed to do that, so maybe if we could find a way to parallel some of the information (automagically would be great but unlikely), that could help for @andrea_r‘s idea of developer vs user.

        • Andrea Rennick 3:59 pm on August 2, 2012 Permalink | Reply

          Yeah I think it;s more an issue of where do we stuff them and how best to link fro the front page.

          The WP LEssons are fine – but they also dive into more of a philosophy of writing. That’s good for going deeper!

          New users need the instruction manual, the step-by-step thingy of these are the menus, here’s what they cover. I had to dig up something or a user yesterday and finding it from the front page or using search *when I knew what I was looking for* was painful.

          As a new user who has no clue? Impossible.

        • Lorelle 4:57 pm on August 10, 2012 Permalink | Reply

          We’ve discussed this before and agreed that the dot com Learn docs are a starting point for us to expand upon with Codex articles that link to the Learn docs then take them several steps further.

    • Hanni 6:43 pm on August 4, 2012 Permalink | Reply

      Heyo! Fantastic!

      It’s been too long since I’ve touched the Codex, and I’m looking to rectify this ASAP! So, @andrea_r, please count me in for any and everything you need. I was sitting in @siobhan’s fantastic panel at WCUK, and am so darn excited to see wheels moving here.

      The separation between user and developer does indeed sound both inherently sensible, and arguably a necessary step on the path towards reducing the barriers to entry as far as possible.

      Looks like the first thing to do is set out perhaps (for example) 3 clear goals, followed by some kind of roadmap, to encompass the fantastic ideas above, (and others!), perhaps?

      (entirely co-incidentally, I’m Happiness Lead over at Automattic, but I’m very much volunteering as me, as I did (too) long ago.)

      • Andrea Rennick 9:47 pm on August 4, 2012 Permalink | Reply

        Whoooooooo! Hanni in the house! :D

        • Siobhan 8:00 pm on August 5, 2012 Permalink | Reply

          I’ve been working on building some doc projects for some pieces of software recently so thoughts of structure are very much on my mind. I thought that if we’re going to talk about structuring the Codex, it might be useful to tell you guys a bit about my workflow see if that generates any discussions on how we can attack this beast. When I think of the Codex I think of a ball of spaghetti, all twisted up in knots. This scares me in terms of figuring out what to do with it. I’ve been working on another open source project that has similar problems. The documentation has been just added to over time as it is needed and so it hasn’t got any real structure. With that I was able to do a content inventory but I suspect that the codex has too many pages for that.

          I conceptualise doc project content in two main ways:
          1. How to? i.e. tutorials, troubleshooting, FAQs
          2. What is? i.e. glossary, references, user guides

          Both of these are needed for complete documentation. The How to stuff is needed for new users, or current users who want to learn new things – if we just have What is docs they won’t have a clue where to get started; and the What is docs are for people who are already used to using the software but want to look something up – it would be a nightmare to have to look things up in a tutorial.

          We have all of these different docs, and the WordPress lessons are split off, but it’s still difficult to know where to go to learn things and where to go for reference stuff. And if you are going for reference stuff it’s difficult to know what is developer and what is user.

          As Andrea has pointed out, we need to split things up into user docs and developer docs. And then for each of these two types of people we need to have “how to’s” and “what is” docs.

          I get the impression that what needs tackling most urgently is the user docs.

          The first thing I do when planning a doc project is ask “What is the novice level of user?” This let me come up with a list of assumptions about who they are and what they need. The entry level of WordPress is pretty low so we can probably assume things like they can use the internet, they may use IE, they probably don’t have in depth knowledge of HTML and CSS. That gives a basic level for where to start off from.

          Then I try to put myself in the head of a user and try to figure out what they will be looking for when they land on the website, and how best can I deliver that information to them. When users go to http://codex.wordpress.org how are they best directed to the information that they need? What questions will they ask? Here are some things I would imagine someone visiting the codex would be thinking:

          I’ve just installed WordPress, how do I get started with it?
          How do I build my awesome WordPress website?
          Someone built a WordPress website for me, how do I use it?
          What do all these thing things do?
          How do I fix this problem I am having?

          That’s pretty much the basics – then you get into developer stuff like developing plugins and themes, but general users probably don’t need to know that.

          If you visit the codex at WordPress.org at the minute, there is a box that says “What You Most Need to Know About WordPress”. These are (along with my comments):
          WordPress Features – doesn’t need to be on the front page of the Codex, would work better on the about menu
          Download WordPress – should have done this by now, doesn’t need to be here
          Installing WordPress – important
          Current WordPress Version – users don’t care about this, and the info can be linked to from download page
          WordPress News – this is linked to on the nav so doesn’t need to be there
          WordPress Support forums – important but also linked to nav
          Troubleshooting – important, but perhaps could be phrased differently
          About WordPress – users don’t care. They’re not going to start looking at this when they arrive
          Glossary – important but doesn’t need to be the first thing users are directed to.

          So out of all of those things that are featured, probably the only one that really needs to be featured so prominently is installation. And arguably that should be linked to mainly from the download page.

          The next section is “Learn How to Use WordPress”. This starts with “getting started with WordPress” and “New to WordPress – Where to Start.” That is kind of crazy. My brain hurts thinking about which one to go to. Both of them are valid, but it’s really a case of too much information. Users shouldn’t have to make these choices. Then there is “WordPress Lessons” and “Learn WordPress” which is also confusing. Part of the problem is that we have too much information, and if we do have the correct info users can’t find it. We should be able to say to them “you want to build a website with WordPress – go here.” You have a problem: go here.

          Anyway, I’m not going to go through the whole page and do an analysis :)

          In terms of the basics of using WordPress, we could probably do pretty much a straight port from wp.com. We’ll need to add some more WP.org specific stuff but most of the basics are covered.

          @hanni suggested coming up with some goals. In an ideal world with infinite time, these would be my goals:
          1. A clear division between developer docs and user docs
          2. A user-friendly landing page that gets users to exactly what they need
          3. Plot a useful journey for different people who want to learn WordPress, from beginner to ninja/rockstar/whatever

          I guess the question is, do we decide on a structure and then slot what we’ve got into that structure, or do we look at what we’ve got and try to reorder than?

          (that was a much longer comment than I intended it to be!)

          • Lorelle 5:00 pm on August 10, 2012 Permalink | Reply

            Excellent. I spent several years mulling over the table of contents for the Codex, and the front page of the Codex is set as it is based on a ton of research and development and just asking at WordCamps and all over. So far, the response has been good and it helps direct people to where they need to go without a lot of clutter on the front page of the Codex.

            The same theories for funneling people need to be applied to ALL of the table of contents.

            The confusion over Learn WordPress and WordPress Lessons is now an issue, I agree. WordPress Lessons have been around since 2004, long before WordPress.com. Same with the the other articles you mention, so inheritance of old material and retitling (that gets crazy when there are so many incoming links to these – have we tracked down who is in charge of redirects and Codex design and management yet?) will be an issue.

            I’m so excited to see these issues that have plagued us so long be cleaned up. YEAH!

    • Anca 2:50 am on August 14, 2012 Permalink | Reply

      I’d like to help out with this as well. As someone who teaches WordPress to people who are just users and also to programmers, the Codex is a great, if frustrating resource. I have limited time to help with this, but I look at the Codex all day long so I’d be happy to tag or propose corrections or questions on discussion pages for review.

      • Ipstenu (Mika Epstein) 3:12 am on August 14, 2012 Permalink | Reply

        While we’re hashing out layout (and I need to nag @nacin again to read his email, he gets a lot), if you guys see stuff in the codex that’s outright wrong or needs explaining more, just edit it. The majority of the ‘content’ pages, I suspect, will stay the same. Like the functions etc.

    • Darren Meehan 12:40 pm on August 15, 2012 Permalink | Reply

      Hi. Helping out with the Codex is something I’m interested in. I’ve been looking for a way to start properly contributing to WordPress and I feel this is it. I’m used to writing guides, and helping people with WordPress, though the workflow and finer details of the Codex is something I’ll need to get used to. Where can I start?

      I hadn’t seen this post, but I made a ticket this morning about the Codex’s header not being updated. http://core.trac.wordpress.org/ticket/21588 I’ve proposed porting the Codex to WordPress. This is also something I’m keen to help with.

      • Ipstenu (Mika Epstein) 1:36 pm on August 15, 2012 Permalink | Reply

        That’s … well. That’s a small part of what might go on here.

        I suspect the Codex, in so far as a repository for what all the various code bits are, will remain as it is. After all, it’s a great coding resource. But the handbook, in whatever form it takes, will be the first run up for ‘How?’ without all the coding.

        For now, go ahead and edit the codex with impunity, especially if you see functions and all that missing info.

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
l
go to login
h
show/hide help
shift + esc
cancel