Due to my nice(?) rearranging of the docs we are not able to update our website without breaking some external links. And this is (to say it friendly) very bad.
But we have updated/new docs that should be published asap. So how can we manage this?
Stefano had an impressing (wild) idea at the GT which sounds very cool, but will unlikely not happen today or tomorrow. I personally wanted to update the site asap, at least with the next release for 2.1.3 - our great bug fix release.
Hmm, what was Stefano suggesting? I'd be interested to know what he's got turning in those gears in his brain :)
I wanted to start this RT to discuss some possibilities, so here are some:
a) I revert the structural changes (cause in the end it's my fault)
+1 for reverting for now.
b) We update and don't care about external links c) We update and care a little bit about external links and redirect a 404 to let's say the start page
Thoughts?
I think we need to make a giant list of all of our docs/pages, what they do, and their current place in the docs structure. There's a lot of stuff out of place, one thing I always notice is the page talking about DELI being switched off. For some odd reason, it just seems like this page does not belong there.
We might need to get away from the "developer" vs "user" notion, because depending on how much about Cocoon you already know, you might have to hack out a new generator (which would seem to imply information in the developer section) while you are really a user.
IMHO, the line between developer and user is blurred, and I think the docs need to reflect this somehow. Touching back to the idea of getting a giant list of all the docs, something I might try is to get a bunch of notecards, and write down each doc on them. If there's a "line" of documents, connect them all together, and shuffle them as a unit. Post-It notes might also work well. This way it's easy to move things around logically without disturbing the file system structure until we have everything sorted out.
From the sounds of it, we're almost at a critical point with the docs. We NEED to make it easy to find things. I've always been of the opinion that the best site docs in the open-source world exist on www.php.net. They combine the "official" docs -- organized very well and logically -- with user-submitted comments, which is sometimes worth more than the real docs. This is something we need to explore for future versions of the site docs, I think, but it may not happen until we have Cocoon serving its own docs.
Carsten
Regards, Tony
