close
The Wayback Machine - https://web.archive.org/web/20130609024122/http://make.wordpress.org:80/docs/

WordPress.org

Make WordPress Documentation

Recent Updates Toggle Comment Threads | Keyboard Shortcuts

  • Siobhan 9:42 am on June 7, 2013 Permalink | Log in to leave a Comment
    Tags: ,   

    The Codex survey is closed and the next stage is to go through the responses. We’re going to do this by user type:

    • Drew – Advanced Users
    • Eric – WP Builder & novice dev
    • Siobhan – Intermediate dev
    • Jerry – WP User

    Please post your results here by Friday 14th June. We’ll be using the results along with other research that’s been going on to do a workshop on the first morning of the docs sprint.

    A few notes for the reviewers:

    • Use the filter at the top to filter by your assigned user group I’ve edited your access so you just get the results for the user group you’re looking at.
    • Remember that if a respondent provides a particularly insightful answer you can click on the report number to the left of their answer and read through that person’s individual report.

    If there’s any other questions you feel should be added to the report, let me know in the comments.

    Outline for Report

    User Type:

    Learning preferences (please list in descending order, noting the percentage):

    Notable answers listed under other:

    Top three places to look for an answer to a question (list in descending order, noting the percentage):

    Are there any other places that these users are regularly looking for answers (make sure you check through the “Option option” answers)?

    How useful is the Codex to this user group?

    What sections of the Codex do these users find most useful?

    What are the main problems these users face with the Codex?

    What documentation would these users like to see more of?

    Based on your review of this survey, do you have any general observations about how this user group is making use of the Codex and documentation more generally?

    Based on your review of the survey, what recommendations would you make specifically about the WordPress Codex that would help these users?

    Based on your review of this survey, make three recommendations for improved documentation that would serve these users:

    Contributing to WordPress Docs

    What percentage of these users have contributed to WordPress Docs?

    What percentage are aware that they can use their WordPress.org login to edit the Codex?

    How can we make it easier for these users to contribute to WordPress docs?

     

    • Eric Amundson 2:22 pm on June 7, 2013 Permalink | Log in to Reply

      Thanks for posting this outline, Siobhan! It’ll make the analysis and reporting a lot easier. :)

      Will post my results ASAP.

  • Siobhan 11:50 am on June 6, 2013 Permalink | Log in to leave a Comment
    Tags: handbook   

    As we discussed in chat before, Nacin created a suite of plugins for the handbooks. These are open source and we’d love for people to contribute to them.

    In light of that, I’ve opened a ticket to get some callout boxes created for the handbooks. It’s be fantastic if someone could put some styles together.

     

    • Kim Parsell 12:28 pm on June 6, 2013 Permalink | Log in to Reply

      I’ve been thinking about the callout boxes, but had no free time to work on it so far. You mentioned setting up the styles as shortcodes – is that still the desired approach?

  • Siobhan 9:42 am on May 31, 2013 Permalink | Log in to leave a Comment
    Tags:   

    New chat time: 16:00 UTC 

    We’re going to have a go at changing the chat time. From now on the Docs/Support chat will be on Thursdays at 16:00 UTC.

    That’s:

    • 6pm Amsterdam
    • 5pm London
    • 12 Noon Eastern
    • 11am Central
    • 10 am Mountain Time
    • 9am Pacific
     

  • Siobhan 12:03 pm on May 28, 2013 Permalink | Log in to leave a Comment  

    Codex Audit & Docs Sprint 

    @jhoffm34 and I have been reviewing the content in the Codex. I exported all of the pages from Google Analytics and then we’ve sorted them into groups of similar content types to see what emerges. You can view the spreadsheet here: https://docs.google.com/spreadsheet/ccc?key=0AnxB9WffF3jOdEFWYWozTGtvNlQ5WGFTQTAxTG55R0E&usp=sharing

    The content we analysed broke down broadly into these different areas:

    User

    • Installing WordPress
    • Getting Started
    • Glossary
    • Blogging
    • Site Builder
    • Troubleshooting
    • Multisite
    • Administration (inc Security?)
    • Getting Help

    There are also about 60 reference pages for the various Panels/Screens. e.g. http://codex.wordpress.org/Administration_Panels

    Developer

    • Setting up a Development Environment
    • How WordPress Works
    • Troubleshooting
    • Code Reference
    • Plugin Developer
    • Theme Developer
    • Server
    • Multisite
    • Administration

    I am keen to have a strict division between the user-focused material and the developer-focused material. Of course, there are times when a developer will be a user (when they are managing their website) and there are times when a user will be a developer (when they tweak their theme) but linking between resources is more effective than putting the user and developer material together.

    I’m reluctant to make major plans for restructuring and changing everything around before we close the Codex survey and analyse the results (some of which are surprising i.e. not everyone hates the Codex), however, I would like to come up with some concrete tasks for the Docs Sprint in a few weeks.

    Therefore, I suggest that the team at the docs sprint tackle the following handbooks that can be built on learn.wordpress.org:

    • Site Builder Handbook
    • Blogging Handbook
    • Editor Handbook
    • Theme Developer Handbook

    Thoughts? Complaints? Suggestions?

     

    • Eric Amundson 4:22 pm on May 31, 2013 Permalink | Log in to Reply

      Hey Siobhan,

      As I mentioned in chat yesterday, I’m willing to help analyze the survey data once you’ve closed it.

      That spreadsheet is mesmerizing; really fun to review. Thanks for the work in putting it together. :)

      Handbook Labels

      I completely agree with the separation of user and developer-focused materials.

      Now that I’ve had a chance to consider this, I’m finding the Handbook labels/names a bit confusing.

      At WordCamps, and WordPress Meetups, you often see three tracks emerge which, to me, seem a natural division for docs:

      • Developers – Plugins, Core – generally a bit more back-end
      • Designers – Designers & Themers – more front-end stuff
      • Bloggers/Users – Content generators

      My questions:

      1. Site Builder Handbook – this sounds like it could be back-end, or plugin stuff, but front-end devs would say they build sites too.
      2. Blogging Handbook – is this really about blogging, or more content generation and using WordPress? If the latter, can we use a more generic term for content authors? I’d guess that 80 – 90% of my clients don’t consider themselves bloggers, even if they regularly generate content for their site. They could be put off by the label.
      3. Editor Handbook – do we need a separate editor handbook, or can it be melded with the Blogging/User Handbook, which would address how to run your site.
      4. Theme Developer Handbook – totally makes sense. As in #1, would a rookie be confused by having a separate Site Builder Handbook?

      • Siobhan 8:30 pm on June 3, 2013 Permalink | Log in to Reply

        Thanks for your feedback!

        I’m not convinced that we should split the docs into Developers / Designers / Users. Developers / Users is a better division. Here’s why I’m convinced we should forget about design:

        • there are loads of design resources on the internet that are better than anything we could do
        • design is affected by trends and fashions and just isn’t something that we can keep on top of. The design elements in the Codex are very dated.
        • people doing front end stuff in terms of code are still developers
        • we should be providing people with the documentation to use the tools, not how to make it look good

        Your questions:

        1. Site builder handbook – I’m not fixed on the name. This will come under User Documentation so it should be clear that it is for anyone who is building a website with WordPress. Definitely open to suggestions.
        2. Blogging handbook – it’s about creating a blog with WordPress. It’s not really about how to write content, but how to use WordPress to write content. WordPress is originally a blogging platform, and blogging at its very core, if people are put off by that title that’s really their problem.
        3. Editor handbook – this has been requested by a lot of people, particularly developers. They want an official handbook that they can give to their clients.
        4. Theme Dev Handbook – the division in the information architecture between developer and user should mitigate any confusion.

        Thoughts?

  • Siobhan 9:11 pm on May 17, 2013 Permalink | Log in to leave a Comment
    Tags:   

    FYI: The Codex & Doc survey is live: http://wordpressdotorg.polldaddy.com/s/documentation-survey

     

  • Drew Jaynes (DrewAPicture) 7:56 pm on May 16, 2013 Permalink | Log in to leave a Comment
    Tags: codex sprint, release   

    3.6 Master Codex changes list (in progress) 

    Since we’re revving up for the 3.6 release and a Codex Sprint, this post will serve as our “master changes list” for 3.6. This list is by no means complete, so leave a comment if you feel like something is missing. We’ll update it as we go. If you’ve completed a todo item, let us know and we’ll check it off for you.

    Pages

    (needed in time for release):

    (anytime)

    General

    Version 3.6

    Post Formats

    Twenty Thirteen

    oEmbeds

    Media

    Developers

    ‘needs-codex’ Trac tickets

    >> Look for the Trac comment where needs-codex was added for more info

    New Functions

    Post Formats

    Audio / Video

    Media

    Revisions

    General

    New Filters

    Deprecated Functions

    External Libraries

     

    • Dave Ross 7:48 pm on May 24, 2013 Permalink | Log in to Reply

      Added some docs for wp_read_audio_metadata, wp_read_video_metadata, and wp_add_id3_tag_data. Not sure how much detail to go into since these are kind of internal functions for the admin interface, but that should be enough for someone to at least know what they do & how to call them.

    • Ben Lobaugh (blobaugh) 2:44 am on May 28, 2013 Permalink | Log in to Reply

      I filled out all the filters except for wp_link_pages

  • Siobhan 8:06 pm on May 9, 2013 Permalink | Log in to leave a Comment
    Tags: admin   

    The folks at Balsamiq have kindly provided us with a free MyBalsamiq account for the WordPress project. If you want to create mockups let me know and I’ll add you to the account.

     

  • Siobhan 2:00 pm on May 9, 2013 Permalink | Log in to leave a Comment
    Tags:   

    In search of WordPress users 

    I am looking for WordPress users to feature in the introduction of the book.

    By WordPress users I mean people using WordPress for their website, blog, etc. I don’t mean people using WordPress as a development tool, to build their business – i.e. people who are outside of the community, who are doing something interesting, and who use WordPress. They’re likely your clients, or your family members, or the people you’ve recommended WordPress to. They may know very little about WordPress – that’s not important, it’s the people that matter. Here’s some examples of people that I’d like to speak to:

    • small business owners (e.g. picture framers, watch makers, grocers, restauranteurs, butchers, bakers, candlestick makers)
    • political activists (particularly anyone who’s blogged from war zones, uprisings, revolutions, or world-significant events)
    • non-profits & charities
    • bloggers (mummy bloggers, fitness bloggers, cooking bloggers, knitting bloggers, fan blogs, gossip bloggers, etc etc )
    • educational institutions (universities, schools, other educational units)
    • governments and government agencies
    • anyone who does something interesting and uses WordPress

    I’m happy to chat with them on Skype or via email. I’ll be asking them what they do day to day, where they do it, and how they use WordPress.

    I’m looking for people all over the world. If you know of someone who you think would be a good fit but they don’t speak English, it would be great if you could act as a translator.

    Any help the community could give me on this would be massively appreciated. I realise that I rarely interact with WP users outside of the community anymore :( . But since many of you have clients, friends, family etc, I was hoping you could point people in my direction.

    If you know of anyone who would be interested, please ask them to email siobhan at wordpress dot org.

    Update: I need to be in touch with people by 27th May.

     

    • Eric Amundson 2:19 pm on May 9, 2013 Permalink | Log in to Reply

      When are you needing responses by, Siobhan?

      We’re sending an email newsletter to customers (who are largely WordPress users) and we’d be happy to include a solicitation for you. :) We were aiming to send next Tuesday, May 14th, but I’ve got a few specific folks in mind that I’ll contact directly (wifey being one – she runs a staffing company site that’s WP-powered).

    • OC2PS 4:42 pm on May 9, 2013 Permalink | Log in to Reply

      I’m a WordPress user. How can I help?

      • Siobhan 7:54 am on May 13, 2013 Permalink | Log in to Reply

        Can you drop me an email at siobhan at wordpress dot org with details about how you use WordPress?

    • Nuno Castelinho 4:53 pm on May 9, 2013 Permalink | Log in to Reply

      My company uses WordPress as a CMS for our site, I can get you in touch with our marketing department, they’re the ones that edit the content and use it to promote and inform our customers (I’m a developer :) ).
      send them an email to: relacoes.publicas@metrolisboa.pt and say I send you :)

      • Siobhan 7:53 am on May 13, 2013 Permalink | Log in to Reply

        Thanks Nuno – can you drop me an email at siobhan at wordpress dot org with details about how you use WordPress?

    • Ana C. 5:04 pm on May 9, 2013 Permalink | Log in to Reply

      Hi! You can count on us :-)
      We manage an hiperlocal news web. Send us your questions.

    • Scott 8:41 pm on May 9, 2013 Permalink | Log in to Reply

      I made my first WP post in July of 2005 and have made my living with WordPress ever since. We’ve developed and SEO’d hundreds of sites, and released half a dozen plugins over the years… I’d be happy to be included – hit me up any time ;) @shendison

      • Siobhan 7:52 am on May 13, 2013 Permalink | Log in to Reply

        Thanks for your interest Scott! For the time being I’m really looking for people who use WordPress as opposed to people running a WordPress-business. I’ll keep you in mind for the future though!

    • Cátia Kitahara 9:49 pm on May 9, 2013 Permalink | Log in to Reply

      Hi Siobhan, I have a client who I think would be a very interesting person to interview. He works in this site: catracalivre.com.br. It’s a calendar of events for free or of low cost. It’s becoming very popular and it’s got between 50 and 100 thowsand visitors everyday. They started very small, but now they are growing very fast. Their project became a study case at Harvard Business School.

    • Jon 3:07 pm on May 12, 2013 Permalink | Log in to Reply

      I’m interested in your request. I am a writer for WPdaily and had an article published recently, http://wpdaily.co/15-wp-life/
      I am a professional guitarist and use WordPress daily for my students as well as for my business.

      • Siobhan 7:55 am on May 13, 2013 Permalink | Log in to Reply

        Hi Jon – can you drop me an email with links to your WordPress website and info about how you use WordPress? Email: siobhan at wordpress dot org

    • Grant Lewis 4:01 am on May 13, 2013 Permalink | Log in to Reply

      Give me a shout, struggling with learning more technically and adding content

    • omshivaprakash 12:00 pm on May 13, 2013 Permalink | Log in to Reply

      Hey Slobhan, I have been a proud user of WordPress for years now and I run many sites for Free Knowledge in Kannada (language code: kn). I’m reachable at info at shivu.in

    • bdthemes 5:42 pm on May 13, 2013 Permalink | Log in to Reply

      Hi i want to translate Bengali language, i already 50% done in locally there anyway to import it in glotpress? or can i get the admin access to management Bengali language? now it’s not fulfill http://bn.wordpress.org/

  • Siobhan 12:24 pm on May 6, 2013 Permalink | Log in to leave a Comment
    Tags:   

    Documentation Survey 

    I’m putting together a survey which we can get people to answer about WordPress’ documentation. I’ll get it online later this week, but I thought it would be worth seeing if you guys had any suggestions for questions that you think would be useful. The aim of the survey is to:

    • help to create a new architecture of the documentation
    • help us to discover pain points
    • create a list of priorities for new documentation

    Okay, here’s what I’ve come up with so far.

    Are you:

    1. WordPress user (I use WordPress to run my website/blog)
    2. WordPress builder (I build and customize websites but I don’t write PHP)
    3. Novice developer (learning to write my first plugins/themes)
    4. Intermediate developer (I write plugins and themes and they’re pretty good)
    5. Advanced developer (I dream in PHP)

    What documentation do you currently use (select all that apply):

    1. Codex – guides
    2. Codex – API documentation
    3. Tutorials and guides on blogs
    4. Books
    5. Breaking WordPress/plugins/themes and putting them back together
    6. Premium services
    7. Screencasts
    8. PHP docs and inline documentation
    9. Forums (like wp.org or stack exchange)

    How useful do you find the WordPress Codex:

    1-10

    What types of documentation/learning do you prefer?

    1. Tutorials
    2. User Guides
    3. Breaking stuff and putting it back together
    4. Screencasts
    5. Code references and API documentation
    6. In-person training
    7. PHP docs and inline documentation

    What’s the first place you go when you have a question about how something in WordPress works?

    Codex
    Google
    Other: [open]

    What do you find most helpful about the Codex:

    [open]

    What problems do you face with the Codex (check all that apply):
    Incomplete documentation
    Out of date documentation
    I can’t find what I need
    Content isn’t clear
    Content isn’t accurate
    Difficult to navigate
    Other:

    What would you like to see more of:
    Tutorials
    Handbooks focused on specific tasks
    Screencasts
    Better code reference
    Better inline help
    ????
    Other:

    What improvements to documentation would improve your experience of using or developing with WordPress:

    [open field]

    Have you ever contributed to the WordPress Codex:

    Yes/No

    Would you like to contribute to the WordPress Codex:

    Yes/No

    If you’ve never contributed to the Codex, can you please say why:

    [open field]

     

    • John Saddington 12:36 pm on May 6, 2013 Permalink | Log in to Reply

      First, since you have developers covered at the top (first section) did you want to include designers, just to get some more demographics? It would be interesting to see the overlap, if anything as designers use the codex too. Perhaps they would call themselves designers + beg/inter/advanced devs?

    • Ulrich 1:32 pm on May 6, 2013 Permalink | Log in to Reply

      For “What documentation do you currently use (select all that apply):”
      I think support forums should be added too.

    • Daniel Bachhuber 5:57 pm on May 6, 2013 Permalink | Log in to Reply

      Thanks @siobhan! A few points of critique:

      • When you mention “documentation you use” or “types of documentation”, you might want to link to examples so the respondent knows what you’re talking about.
      • Unless you need the data for statistical purposes, 1-10 answer types are generally not that useful.
      • I would ask “What’s the first place you go when you have a question about how something in WordPress works?”

      I think the survey will work well for identifying pain points and priorities, but I’m not sure how well it will work for creating a new documentation architecture.

      • Siobhan 12:23 pm on May 7, 2013 Permalink | Log in to Reply

        Thanks for this

        • I’ll add links to any that require clarification once I make the survey. Good suggestion.
        • The 1-10 answer should give us some sort of idea of how well the Codex is fitting the needs of users of different levels of experience.
        • nice question. Added.

        Yes, you’re right about it not being particularly useful for creating the new documentation architecture. We’re using analytics to get a sense of what we currently have and to come up with the new architecture. I’m hoping that this survey will help us to prioritize what tasks we tackle first.

    • toscho 10:59 am on May 7, 2013 Permalink | Log in to Reply

      I use only two sources for documentation: wordpress.stackexchange.com and the source code. Might be worth to add.

    • esmi 12:15 pm on May 7, 2013 Permalink | Log in to Reply

      Under “Are you:” (ie WP user type), can I suggest adding something like “WordPress support volunteer (I help out on the support forums regularly)”? Perhaps at position 3? Not all support regulars are PHP coders but their feedback on documentation could be especially useful.

      • Siobhan 12:27 pm on May 7, 2013 Permalink | Log in to Reply

        I agree that WP support volunteers would have useful feedback, but this survey is to gauge the usefulness of the Codex to WP users of differing skill levels. The first question isn’t intended to identify everyone who uses the Codex, but the level of skill of people who use it.

        However, this does make me think that what would be useful is a survey targeted at support forum volunteers on the usefulness of WP documentation. They will look at it from a different angle to users. I had thought a while back about extending a survey like this out to support people at commercial WP businesses to see what areas of WP documentation they are consistently sending customers to, and what areas are lacking.

    • rachel_mccollin 2:47 pm on May 7, 2013 Permalink | Log in to Reply

      I would suggest adding a positive question in addition to the one asking what problems people experience with the Codex. Before asking them that (and putting them in a negative frame of mind), we can ask what they find helpful about the Codex, and list the opposite of those things listed for problems.

    • Vid Luther 5:16 am on May 8, 2013 Permalink | Log in to Reply

      I’d like to add “Systems Adminstrator” as a clause as well. How to build and configure performant systems should also be part of the Codex. I believe a few months ago, there was a call to adopt a part of the Codex, we’ve been thinking of adopting the Nginx side.

      • Siobhan 10:09 am on May 8, 2013 Permalink | Log in to Reply

        A Systems Admin handbook is definitely on my radar. I’ve been looking at the stats and current architecture and we do have an Nginx page which receives about 9,000 hits a month. I’d love to get in touch with you once we’re ready to move on that side of things to see if you guys have time to help out with it.

    • Eric Amundson 12:50 pm on May 9, 2013 Permalink | Log in to Reply

      Yes, thanks @siobhan!

      I agree with Daniel about the need for examples in the “What documentation do you currently use” section, especially point numbers 5 & 6. In fact, #5 really doesn’t seem like a form of documentation; more a style of learning. Usually when I break stuff, I end up referring to WP documentation to fix.

      Maybe a bit picky, but under “What types of documentation/learning do you prefer?,” I’d clarify #1 to say something like “Written Tutorials” because there are tons of sites that provide lots of video tutorials. I understand the difference, but it could help clarify for someone for whom English is a second language.

      If you were to add that, you might consider adding “(video)” after Screencasts, or list it as “Screencasts/Videos.”

  • Drew Jaynes (DrewAPicture) 9:16 pm on May 2, 2013 Permalink | Log in to leave a Comment
    Tags: core,   

    Revisions help tab 

    revisions_help_tab

    Yesterday in DevChat, @ocean90 requested we write a help tab for the new revisions screen. I’ve uploaded a first-run patch and am looking for feedback and revisions (ha) on that text.

    I’d just like to note that I think we can be succinct about this without leaving out important information.

    The ticket and patch are on the #23899 ticket.

    The following is the first-run text:

    Tab: Overview:

    This screen is used for managing your content revisions.

    Revisions are saved copies of your post or page, which are periodically created as you update your content. Text highlighted in red shows what content was removed, highlighted in green shows what content was added.

    From this screen you can review, compare, and restore revisions:

    • To navigate between revisions, drag the slider arrow left or right or use the Previous or Next buttons.
    • Compare two different revisions by selecting the ‘Compare two revisions’ box to the side.
    • To restore a revision, click the Restore This Revision button.

    Tab Sidebar:

    For more information:

    Revisions Management
    Support Forums

    Side note: The Revisions Management page is slated for pre-sprint release, in other words, it’ll be done in time for the 3.6 release so forum folks have something to reference.

     

    • esmi 9:35 pm on May 2, 2013 Permalink | Log in to Reply

      Text highlighted in red shows what content was removed, highlighted in green shows what content was added.

      Shouldn’t there be an extra “text” in the second half of the sentence?

      Can I suggest that we avoid using terms like “red” and “green” as the sole descriptions? Maybe use something like:

      Text on the left (highlighted in red) shows what content was removed, text on the right (highlighted in green) shows what content was added.

      • Siobhan 9:20 am on May 3, 2013 Permalink | Log in to Reply

        Some changes (incorporating Esmi’s suggestions too:

        Tab: Overview:

        This screen is used for managing your content revisions.

        Revisions are saved copies of your post or page, which are periodically created as you update your content. The red text on the left shows the content that was removed. The green text on the right shows the content that was added.

        From this screen you can review, compare, and restore revisions:

        • To navigate between revisions, drag the slider arrow left or right or use the Previous or Next buttons.
        • To compare two revisions select the Compare two revisions box.
        • To restore a revision, click the Restore This Revision button.

        Tab Sidebar:

        For more information:

        Revisions Management
        Support Forums

← Older posts

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