Upgrade StorageNew Documentation?
So apparently an overhaul of the documentation is planned
http://friendfeed.com/lsw/db993930/zotero-fans-api-is-live-that-allows-creating
I think that's a great. While content-wise I think Zotero documentation is actually quite good (as evidenced by the fact that we can answer many questions on the forum with a link) it does suffer a bit from a lack of thought-out structure (as evidence by the fact that we're getting many questions that can be answered by a link).
What would be good to know, though, is a rough outline of these planned changes. Are only the parts of the wiki that are currently locked going to be revamped? Is the whole documentation going to be affected? Does it even make sense to continue to contribute to the wiki at this point? It'd be great to hear a couple of sentences from Debbie about the nature of the planned changes.
http://friendfeed.com/lsw/db993930/zotero-fans-api-is-live-that-allows-creating
I think that's a great. While content-wise I think Zotero documentation is actually quite good (as evidenced by the fact that we can answer many questions on the forum with a link) it does suffer a bit from a lack of thought-out structure (as evidence by the fact that we're getting many questions that can be answered by a link).
What would be good to know, though, is a rough outline of these planned changes. Are only the parts of the wiki that are currently locked going to be revamped? Is the whole documentation going to be affected? Does it even make sense to continue to contribute to the wiki at this point? It'd be great to hear a couple of sentences from Debbie about the nature of the planned changes.
She asked me to help out, as I've been one of the more active wiki editors, but obviously we'd like to allow everybody to chime in. Any suggestions on how to collaborate on restructuring the wiki are very welcome (for now, Debbie and I just work in the wiki at http://www.zotero.org/support/dev/start/index ; we can move the pages to their proper places when they're done).
That will also let you set up a wiki account if you don't have one.
Yes, I know about the dev pages updates, and I'm very grateful for your ongoing work on them. They're exciting, accurate, and promise to be pretty comprehensive. And I'll be contributing too as the April seminars near.
There has been a little more back-channel communication than perhaps is necessary, and I hope we'll soon work out ways to keep these things nice and transparent to all interested parties.
Thanks for the comments. Was planning on sending out a notice on these matters sometime tomorrow, but now is as good a time as any :)
As you may have heard, there are going to be some free Zotero developer workshops happening in at UW Madison and the Newberry in Chicago in mid-April.
Avram Lyon contacted me earlier this month about wanting to teach Zotero in the Chicago area, and I thought it'd be a good time to think about getting more tutorial-style reference docs together for teaching people dev, in video and text.
These workshops are really exciting because they’ll teach folks with a range of tech know-how how to program for Zotero. They'll not only widen the base of people who can tweak Zotero for their needs, but provide people with new web programming skills (Javascript, basic xpath etc) that can help them in an array of web-related activities. This workshop for some will be a “learn how to web-program with Zotero as your tool.”
Given that only knowledge of HTML is being required for these workshops, it is necessary to augment the dev docs in some places and to provide a clear outline re: the basics of Zotero programming, what is involved for each task, etc. That is, programming with Mozilla technologies, version control, javascript etc will be new to some people, and so this new developer outline (which will likely become the new dev index, or a large part thereof) will help people better understand where and how they can contribute. The importance of doing this won’t just be in making a workshop outline either, but rather it’s about providing people everywhere with a guide on how to get involved with Zotero programming, doc writing, and translating. (So for now, the focus is just to fix the dev section - support section updates will happen later on.)
I apologize for keeping folks out of the loop. The reason you haven't seen or heard much about doc updates (I’d mentioned it only briefly in an email to Zotero contacts last month) is because these workshops, which have hastened the need for improved docs, were organized rather quickly in the last couple of weeks, and finally there’s been time to do the much-needed new dev outline, the draft for which was just put up late last week on an orphan wiki page. Also, because I’m new, I’ve been starting the process by reaching out to people here and there whose names have been passed along to me, but this is certainly not an attempt to close participation off. In fact, help is more than welcome and very much needed!
Here's a link to the dev index (currently a rough draft!):
http://www.zotero.org/support/dev/start/index
Right now, there’s an attempt to organize kb, map existing dev content to the new sections of the index (without corrupting existing links), etc. As you’ve pointed out, a lot of the existing content is good, so all I’m looking to do, with the help of others, is put everything into a more easily navigable structure, with some augmented content for certain sections to make things comprehensible to beginners.
Wiki Docs that people are working on now will not be stripped out later, so please don't cease working on any new docs.
That being said, this restructure is a big task, and it would be great have more folks:
Provide input for the structure of this new dev index
Help with mapping the existing content into new sections (I’m trying to do the bulk of this now)
Pick the sections for which they wouldn’t mind writing blurbs/augmenting content
Coming up with a maintenance plan for the dev sections
If, as a developer, revamping the structure is something you (or anyone you know) would be interested in, please send me an email at dmaron@zotero.org. I’d like to get a Skype group chat together later this week or early next week to discuss any changes or garner opinions for dev section improvements.
Hope this clarifies things. Please feel free to email or post with further questions.
Best,
Debbie
Look forward to your email. Yep, Avram had mentioned that you may be able to assist with the sessions. Didn't want to bug you though til I had the scheduling firmed up (we're still waiting on one more school).