About Magento 2.0 developer documentation

With Magento 2 dev beta we also launch documentation in GitHub. Here is a bit more info for those interested.

Hi everybody, this is Bradburn Young with a guest post. Thanks to Alan for lending me his space to talk to you here.

I lead a team of technical writers here at Magento. We publish Magento 2.0 developer documentation, and I’m writing the community of Magento developers to let you know that we’d like to hear from you. We rely sincerely on the understanding and experience of our developer community to help us shape documents that make your work easier to do. I’m going to tell you about a step we’ve taken to make it simpler for you to talk directly to us.

For the Developer Beta release, we’ve moved our documentation from the old public wiki to a new location and platform, http://devdocs.magento.com. Below are some basic questions and answers to get you started interacting with our documentation.

What kind of site is that?

It’s a GitHub site, rendered by Jekyll. Here’s our repository: https://github.com/magento/devdocs.

What are you doing on GitHub?

We publish here because the code we’re writing about lives here on GitHub, and because we hope you’ll like using the familiar interface of pull requests and issues to contribute to the documentation.

How often do you publish new content?

We publish all the time, but we work in two-week sprints and publish the bulk of our updates at the end of each sprint. We’ll let you know on the site what’s new in the documentation at the end of each sprint.

What about reference documentation for web APIs and service contracts?

We have been annotating the code with documentation comments like the ones here. We’ll be publishing generated API references based on such annotations, along with code samples for you to play with. For basic information about using our APIs, see Getting Started with Magento Web APIs.

Do we want any help with this?

Yes, we need your help. We write for both experienced and beginning developers, and it helps us when you tell us that we need to clarify or give fuller treatment of a topic, or that you’re trying to get something done and you find a gap in our documentation, or that there’s a topic you’d like to hear about or some sample code you’d like to see. We think of our documentation in terms of use cases, about what exactly you’re trying to accomplish on a given day. We would like to hear from you about your own specific use cases. Is there something you’re trying to do that isn’t fully covered in our documentation? We’re all ears—let us know!

You can create a pull request or issue on any of our pages. To get started, just go to one of our pages and look for this in the upper right-hand corner:

GitHub Edit Short

Do you see any room for improving the site?

We see quite a lot of room, yes. We need to implement search, make the site responsive, and fix some display issues. Candidly, we’ll probably never stop fussing with it. Our site is a work in progress, and we’ll improve it as time goes by.

Who are you?

Some of us have been writing developer documentation for Magento 2.0 since the early days of the promise that one day Magento 2.0 would arrive. As technical writers, we try to implement all of the processes that we describe. We also rely heavily on our developer colleagues for solutions, examples, best practices, and walkthroughs.

What we produce is official product documentation, which means we stand behind it. Our obligation is not only to write it once, but to remain responsible for maintaining it. We will fix it if it’s wrong, and respond to your suggestions when you tell us it can be improved.

You can reach me at styoung@ebay.com, and I’m @bradburn on Twitter.

Was this guest post useful? Want to see more? We are investigating launching a developer blog early next year. All feedback or encouragement welcome!

One comment

  1. Thanks Bradburn for this guest blog post. I’m looking forward to a developer blog. It’s great to get to know different faces behind Magento and learn about Magento from different angles. Keep it coming!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: