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?
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:
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.
Was this guest post useful? Want to see more? We are investigating launching a developer blog early next year. All feedback or encouragement welcome!