Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
Le Samedi, 11 oct 2003, à 15:33 Europe/Zurich, Stefano Mazzocchi a écrit : ...I had two names "Hyperbook" and "Papyrus", but both are probably infringing some trademark. I'll try to come up with something that is "print" or "publishing" or "learning" related if you have a suggestion, it's a good time to speak up... How about "LearningTrove" ? -Bertrand
Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
Stefano Mazzocchi wrote: ... NOTE: this is *NOT* something that will replace either forrest or lenya. In fact, the idea of this system is to show off *all* the cocoon-related technologies we have in one big showcase for our own use. So, both forrest and lenya should be happy to participate into this because it might give them even more exposure and ideas for new features or simply more itches to scratch that would revamp the various communities. Forrest has basically decided to focus on the presentational part of providing content, so the proposed system is a perfect fit for Forrest. Lenya on the other hand is much more oriented on the editing. I had thought that we could somehow make Forrest use Lenya, but never got to it because something seemed wrong. having a clear separation of view generation (Forrest) and editing (Lenya) seems like a perfect wat to reuse the systems getting the best out of them. I would propose that we seek to make Forrest be able to generate the site from what you think is necessary. OTOMH that means adding navigation concerns to site.xml and an id mechanism for files. Then we can move the docs to the new layout and have Forrest publish this test site regularly. Then comes the Lenya integration, that has to be able to edit this thing. Guys, let's move the discussions about what is needed over to forrest-dev, because we already had a lot of discussions about similar stuff. Oh, and take a look at site.xml, as it may be used for what is needed. Maybe I lost some threads here, maybe it's just that I wasn't at the GT, but I have the feeling that I don't know what is needed for this by Forrest. If someone would post on Forrest-dev a list of things that Forrest should be able to do it would be great to get us started. :-) -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
On Saturday, Oct 11, 2003, at 14:58 Europe/Rome, Bertrand Delacretaz wrote: Le Samedi, 11 oct 2003, à 14:11 Europe/Zurich, Stefano Mazzocchi a écrit : ...I think the documents should have a *numerical* identifier that equates them with a URI. http://cocoon.apache.org/cocoon/LO/3948494 I like the "unique ID" idea, OTOH not having descriptive names makes it hard for people to locate the appropriate file to edit in a directory, decode CVS change messages, etc. How about naming files like 3948494-some-descriptive-name-for-humans-here.xml It's like suggesting to have a BugID "39484-my-file-can't-be-found" as the primary key of the bug table in mysql, just because people might want to edit bugs by hand inside the database!! When you have bug emails, you get the bug ID which is unique and semanticless. if the bug changes course over time (might even change title in the more advanced tracking tools!), the "issue" is the same and can change without breaking because the contract is nameless. Think about TCP/IP: instead of placing a human identifier at the IP level, they used a lookup mechanism. This is exactly the paradigm that we should follow, IMO. Where what follows the first dash is ignored by the publishing system (which will need to check the uniqueness of IDs then)? Messy. what would something like this behave? 22003-this-is-first-doc.xml 22003-this-is-second-doc.xml ..where "LO" stands for "learning object". hehe ;-) ...-create a very simple publishing system for now (Forrest probably?), until the new docs system moves forward a first step could be the introduction of files that contain navigation structure. They could also be xslt processed to generate .htdocs file for mod_rewrite instructions so that we don't expose those URI directly but we wrap them with nicer-looking addresses. [it's the static equivalent of a lookup]... Sounds good. or we might use site:-based address translation capabilities of forrest. even if I'm not exactly sure on how this works (haven't look at forrest in a long time). P.S. We need to find a name for this new doc management system - I'm low on ideas noew but maybe CDMS? Cocoon Documentation Management System? -1 for acronyms. Actually I don't like them either ;-) But we need to name this thing at some point. True. I had two names "Hyperbook" and "Papyrus", but both are probably infringing some trademark. I'll try to come up with something that is "print" or "publishing" or "learning" related if you have a suggestion, it's a good time to speak up. NOTE: this is *NOT* something that will replace either forrest or lenya. In fact, the idea of this system is to show off *all* the cocoon-related technologies we have in one big showcase for our own use. So, both forrest and lenya should be happy to participate into this because it might give them even more exposure and ideas for new features or simply more itches to scratch that would revamp the various communities. -- Stefano.
Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
Le Samedi, 11 oct 2003, à 14:11 Europe/Zurich, Stefano Mazzocchi a écrit : ...I think the documents should have a *numerical* identifier that equates them with a URI. http://cocoon.apache.org/cocoon/LO/3948494 I like the "unique ID" idea, OTOH not having descriptive names makes it hard for people to locate the appropriate file to edit in a directory, decode CVS change messages, etc. How about naming files like 3948494-some-descriptive-name-for-humans-here.xml Where what follows the first dash is ignored by the publishing system (which will need to check the uniqueness of IDs then)? ..where "LO" stands for "learning object". hehe ;-) ...-create a very simple publishing system for now (Forrest probably?), until the new docs system moves forward a first step could be the introduction of files that contain navigation structure. They could also be xslt processed to generate .htdocs file for mod_rewrite instructions so that we don't expose those URI directly but we wrap them with nicer-looking addresses. [it's the static equivalent of a lookup]... Sounds good. P.S. We need to find a name for this new doc management system - I'm low on ideas noew but maybe CDMS? Cocoon Documentation Management System? -1 for acronyms. Actually I don't like them either ;-) But we need to name this thing at some point. -Bertrand
Re: [RT] Moving towards a new documentation system (was: [RT] Updating the website)
On Saturday, Oct 11, 2003, at 11:36 Europe/Rome, Bertrand Delacretaz wrote: Le Samedi, 11 oct 2003, à 04:21 Europe/Zurich, David Crossley a écrit : Tony Collen wrote: ...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. +1 ... we have talked about that many times. Almost every user is a developer. Anyway "Trails" are better navigation method. +1 I'm starting to think (and I think this resonates with what Tony was saying) that the physical structure of the docs should be flat, wiki-style, having all docs "files" (real files or generated) in a single directory, of very few directories like "reference", "documents" and maybe "technotes". eheh, seems like the memes start to percolate. good. I think the documents should have a *numerical* identifier that equates them with a URI. http://cocoon.apache.org/cocoon/LO/3948494 where "LO" stands for "learning object". We can then build all kinds of navigational structures, trails, multiple tables of contents, beginners/advanced, whatever (again picking up on wiki idea of a flat page structure with many navigation paths), but the path to a given document stays valid forever unless documents are removed. Exactly. Right on. With a numberical identifier, we can even keep the page if we change its title (this will ease refactoring and reduce the chance of future migration... btw, this is the approach used by DOI and DSpace... note that this is exactly the same concept I use for linotype, where news are identified by a unique incremental number) Of course we forfeit compatibility with our existing docs URLs, but I think this is needed anyway to move forward. Big +1, we have to cut the rope at some point. This might also make our remodeling easier: -move all existing docs to a small number of directories like above, "big bag of docs" +1 -rename docs as needed to give them permanent names yep -create a very simple publishing system for now (Forrest probably?), until the new docs system moves forward a first step could be the introduction of files that contain navigation structure. They could also be xslt processed to generate .htdocs file for mod_rewrite instructions so that we don't expose those URI directly but we wrap them with nicer-looking addresses. [it's the static equivalent of a lookup] -start building the navigations, trails, tables of contents incrementally yes, the links can be refactored without -if the docs format changes for the new doc management system, navigation definitions stay valid true and in the future, we can still use those to seed a more dynamic approach. I think we need to find a way to get started with this docs remodeling without having to wait too long on our improved doc management system - if an incremental path like above works it might help us get > started. Thoughts? big +1 -Bertrand P.S. We need to find a name for this new doc management system - I'm low on ideas noew but maybe CDMS? Cocoon Documentation Management System? -1 for acronyms. -- Stefano.
[RT] Moving towards a new documentation system (was: [RT] Updating the website)
Le Samedi, 11 oct 2003, à 04:21 Europe/Zurich, David Crossley a écrit : Tony Collen wrote: ...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. +1 ... we have talked about that many times. Almost every user is a developer. Anyway "Trails" are better navigation method. +1 I'm starting to think (and I think this resonates with what Tony was saying) that the physical structure of the docs should be flat, wiki-style, having all docs "files" (real files or generated) in a single directory, of very few directories like "reference", "documents" and maybe "technotes". We can then build all kinds of navigational structures, trails, multiple tables of contents, beginners/advanced, whatever (again picking up on wiki idea of a flat page structure with many navigation paths), but the path to a given document stays valid forever unless documents are removed. Of course we forfeit compatibility with our existing docs URLs, but I think this is needed anyway to move forward. This might also make our remodeling easier: -move all existing docs to a small number of directories like above, "big bag of docs" -rename docs as needed to give them permanent names -create a very simple publishing system for now (Forrest probably?), until the new docs system moves forward -start building the navigations, trails, tables of contents incrementally -if the docs format changes for the new doc management system, navigation definitions stay valid I think we need to find a way to get started with this docs remodeling without having to wait too long on our improved doc management system - if an incremental path like above works it might help us get started. Thoughts? -Bertrand P.S. We need to find a name for this new doc management system - I'm low on ideas noew but maybe CDMS? Cocoon Documentation Management System?
Re: [RT] Updating the website
Tony Collen wrote: > Carsten Ziegeler wrote: > > 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 :) It is going to be great when virtual participants can be at the GT2004 (surely our "collaborative tools and techniques" experiment will have progressed by then. > > 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. This is just a Random Thought at this stage, so it is a bit early to vote. Lets discuss options first. I too prefer to revert and i will try to help. We need to do this re-structure steadily and in the upcoming 2.2 module. > > 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 used to have that. There was an automatically generated table of contents which aggregated all of the book.xml files and made a list of every doc. It seems to have been removed but not replaced with anything better. Yes, such a list, and past discussions and previous "table of contents" (= structure) proposals will help us to sort it. > 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. +1 ... we have talked about that many times. Almost every user is a developer. Anyway "Trails" are better navigation method. > 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. Come on down, you have some great ideas. > 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. Yes, surely we must be getting closer to EODF - eat our own dogfood. But still, Forrest is surely clever enough to do some of these requirements now. --David
Re: [RT] Updating the website
Bertrand Delacretaz wrote:
> Carsten Ziegeler a écrit :
> > ...
> > c) We update and care a little bit about external links and
> >redirect a 404 to let's say the start page
>
> +0.5 (meaning "ok but cannot help ATM")
>
> but maybe to an explanations page ("we're remodeling") instead of the
> start page
>
> -Bertrand
No matter which option that we choose, i think that this
"redirect to explanation page" is a good thing.
--David
Re: [RT] Updating the website
Carsten Ziegeler wrote: 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
Re: [RT] Updating the website
On Fri, 2003-10-10 at 10:38, Carsten Ziegeler wrote: > 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. agreed, we need to be able to update the site. > > I wanted to start this RT to discuss some possibilities, so > here are some: > > a) I revert the structural changes +1 I fail to see how the new structure is any better then the old one, so we can as well keep the old one. -- Bruno Dumon http://outerthought.org/ Outerthought - Open Source, Java & XML Competence Support Center [EMAIL PROTECTED] [EMAIL PROTECTED]
Re: [RT] Updating the website
Le Vendredi, 10 oct 2003, à 10:38 Europe/Zurich, Carsten Ziegeler a
écrit :
...
c) We update and care a little bit about external links and
redirect a 404 to let's say the start page
+0.5 (meaning "ok but cannot help ATM")
but maybe to an explanations page ("we're remodeling") instead of the
start page
-Bertrand
[RT] Updating the website
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. 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) 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? Carsten
