Documentation overhaul

Escrito por Mark Forrester on febrero 26, 2013 News, Product News.

Today we are proud to launch the new home for all our product documentation – docs.woocommerce.com.

The magnitude of this undertaking hopefully does not go unnoticed by our users, rest assured there’s been a lot of content curation and development that’s gone into it.

Trimming fat & legacy

Previously our 100+ theme user manuals were housed as WordPress pages on WooThemes.com, whilst our WooCommerce user guide, and all the extension manuals, were housed on a separate WordPress installation running our Wikeasi theme. Plugins like WooSlider and WooSidebars were articles within our knowledgebase. Managing the content and removing legacy has proven difficult given the distributed content.

As WooThemes has grown and it’s product catalog diversified the need to get all documentation under one roof has become more and more apparent. Coupled with our massive drive to deliver customer happiness through brilliant support in Zendesk we feel we are finally getting closer to our ambitious goals for this quarter.

We worked with the hugely talented WordPress wordsmith Siobhan McKeown in auditing our existing documentation and providing us with a spec for a better workflow and more usable format for the content.

An initial wireframe for the proposed theme document layout by Siobhan. Less is more.
The new theme documentation format.

Identifying audiences

From Siobhan’s documentation review:

Each piece of documentation should be directed towards a specific audience.
Never provide developer documentation to end-users. If you want a user to be able to do what they need you should give them exactly the right docs, with nothing to get them confused. And you shouldn’t expect developers to sift through user docs to get information about hooks or filters.

We’ve ensured this by distinguishing between the different types of user and developer documentation using keys.

Search results identifying user and developer docs.

It’s a work in progress people!

As always it’s a constant work in progress and we’ve allocated support staff to further curate the content, iron out bugs and improve the usability of the new system according to Siobhan’s documentation best practice:

  • Write short documents
  • Document when the product is in release candidate
  • Avoid information overload
  • Provide task-based steps for users
  • Keep user and developer documentation separate
  • Complement content with tutorials on your blog

Documentation is like having a garden. It needs to be constantly trimmed back and updated or it gets into a horrible mess.

With docs now powered by it’s own WordPress installation on a custom built theme we believe it’s finally worthy of the WooThemes seal of approval.

View the Docs
cta-banner-10-product-page-v2_2x

27 Responses

  1. bigsky
    febrero 26, 2013 at 3:31 pm #

    Thank you – great work.
    Is there documentation for Features and Testimonials Plugins?

    • Matty Cohen
      febrero 26, 2013 at 4:21 pm #

      There is, yes. 🙂

      This documentation is packaged within the plugins’ “readme.txt” files as well as in the “Other Notes” section on the Features and Testimonials plugin listings on WordPress.org.

      We’ll look into adding this documentation to our new docs website as well. 🙂

  2. cubewebsolutions
    febrero 26, 2013 at 4:22 pm #

    502 Bad Gateway when I go to that link for docs.woocommerce.com.

    • iowa600
      febrero 26, 2013 at 4:57 pm #

      Ditto.

      • samuelmaes
        febrero 26, 2013 at 5:26 pm #

        +1.

        tweeted this already.
        this is becoming quite a repetitive issue presently =(

  3. mcnabbj2
    febrero 26, 2013 at 5:28 pm #

    Awesome! I have been frustrated by the old format. This seems really promising.

  4. jamesmarsland
    febrero 26, 2013 at 6:33 pm #

    Hi Guys,

    Looks great,

    A couple of things
    – You’ve still got the wpengine quick links activated on the admin toolbar
    – Our PP wooslider videos aren’t showing 🙂

    Jamie

    • wdh
      febrero 26, 2013 at 7:10 pm #

      Thanks for the heads up Jamie 🙂

      We’ve fixed the admin bar issue and we’ll look into getting your awesome videos showing 🙂

  5. Estella Vidal
    febrero 26, 2013 at 6:34 pm #

    GREAT!!
    Thanks ninjas 🙂

  6. smckeown
    febrero 26, 2013 at 6:57 pm #

    Looks great guys! Congrats on all your hard work 🙂

  7. dotp
    febrero 26, 2013 at 10:26 pm #

    Nice work. Looking forward to using it.

  8. erlend_sh
    febrero 26, 2013 at 10:41 pm #

    Beautiful. Amazing work guys. It’s been a long time coming, but it’s no small feat.

    This should be the base of Wikeasi 2.0 (plugin this time).

  9. erlend_sh
    febrero 26, 2013 at 11:00 pm #

    The custom link (below drop-down) to WooCommerce development is a little bit confusing, especially because of the breadcrumbs.

    The hierarchy is currently like this:
    Documentation > Developer Reference

    Yet I was expecting this:
    Documentation > WooCommerce > Developer Reference

    Once I’ve entered the “WooCommerce space”, I expect there to be straight forward ways for me to get to the top-level.

    • Sandie
      febrero 27, 2013 at 4:10 pm #

      I agree. Breadcrumbs are really important on this type of site. Could you also add a “Docs home” label to the front of the breadcrumb? It’s not intuitive to use the docs.woocommerce.com site logo to get to the documentation home, given it looks exactly the same as the site logo on the main site, you tend to expect it to take you to the main website homepage…

  10. erlend_sh
    febrero 26, 2013 at 11:05 pm #

    I also don’t see why there needs to be an extra “Go” action for the drop-downs. Once you’ve clicked a menu item you’ve clearly made your choice already, just take me there already 😉

  11. A
    febrero 26, 2013 at 11:21 pm #

    Any plans to make a similar documentation theme for WooThemes clients?

    • sitebuilderone
      febrero 27, 2013 at 1:50 am #

      +1 on this one as well.

  12. cosmonaut
    febrero 27, 2013 at 7:07 am #

    The delineation between User and Developer docs is fantastic! We run into those issues all the time with our working group as not everyone on our team is proficient in full-blown site development. We’re excited to have chosen WooThemes to team up with!

    • erlend_sh
      febrero 27, 2013 at 9:33 pm #

      Agreed, this tiniest of details is absolutely brilliant.

  13. Jason Glaspey
    febrero 27, 2013 at 8:47 am #

    Hey guys. Great great work. Very impressed with the ambition to and effort going into making all of Woo even better. As someone who’s owned/ran a fast growing company, recognizing when legacy systems are getting in the way of growth can be difficult. And taking on the enormous tasks of rectifying solutions that once worked, but no longer are keeping up with the current needs can be daunting. So huge congrats.

    I’m sure there will be bugs, mixups, and whatnot, but you guys are doing a great job. Don’t let whiners whining about 502s get you down, this is great work and will be amazing as you continue to evolve.

    Keep at it.

  14. lyndawass
    febrero 28, 2013 at 12:15 pm #

    This documentation for your site is looking good and much interesting than the existing….

  15. Björn
    febrero 28, 2013 at 3:16 pm #

    Menu option: WooCommerce-> http://wcdocs.woocommerce.com/

    Did a search in there, browsed to page 2 using http://wcdocs.woocommerce.com/?s=requirements and was redirected to http://docs.woocommerce.com/document/merchant-warrior/ ??

  16. uddhava
    marzo 4, 2013 at 12:16 am #

    Whenever i search in the docs i get the same results, that are not at all helpful.
    Maybe the search can be limited depending on the page that you are on.
    For example on this page:
    http://docs.woocommerce.com/product/woocommerce-plugin/developer-reference/

    If i search for “cart navigation” i get the same results as the main docs page. Not very helpful. And the search shows me the user document for the Hustle theme as first item. (when i wanted to find the correct snippet to change the cart item in the navigation menu.

  17. oxfordshireweb
    marzo 4, 2013 at 1:56 pm #

    It seems like the WooCommerce theming docs have pretty much gone? or perhaps I just can’t find them?

  18. practutor02
    marzo 6, 2013 at 11:37 am #

    Thanks a lot for this post!

  19. Bal
    marzo 28, 2013 at 2:00 am #

    any plans on replacing the hooks & filters reference for Canvas?

    • Michael Krapf
      marzo 28, 2013 at 2:12 pm #

      Hey Bal,

      That reference is still available within our helpdesk knowledge base – http://support.woothemes.com/