Website redesign (was Re: Please clear up DarwinPort/MacPorts confusion)
On Apr 6, 2007, at 2:45 PM, Sean Fulton wrote:
That's all fine and good but I want jump in the pile-on and say that the site and documentation need some serious attention. Having outdated docs in SVN is less than ideal.
Now that 1.4 is out will there be some effort to providing useful documentation? Do the project leads need volunteers to help? I'm willing.
At first I thought about saying "Ooohh, we so *totally* need volunteers to clean-up/improve our site!!", but then I asked myself "improve *how* and *what* exactly?" I think it's pretty clear to everyone that we need a major website and documentation overhaul (that said with my MacPorts Manager hat on!), so I'd say that before we do any minor and possibly random rearrangements and/or cleanups here and there, one thing we need to do, as a team and as openly as possible, is to discuss what we would like to see in a new website (including everything: welcoming portal, downloads section, documentation section, headlines, trac integration, per ports page, etc...). I've been thinking about bootstrapping this discussion and putting forth some initial ideas into the mix, and maybe even asking (inviting) some of the WebKit folks to give us a hand with the redesign (they obviously have a thing for websites ;-); but other than that, we as a team don't have much of a roadmap with respect to our site, admittedly and unfortunately. I'll bring the subject up with the other managers and MacOSForge admin personnel to at least get an initial feeling of what we can do (not only resource wise but also with respect to some guidelines we have to stick by), and will post again on the subject when I get a clearer idea. I think it's wise to ask everyone with either a dire stray need for a new site (because the current one sucks!) and/or the appreciated willingness to help, to wait until such time for us to better coordinate all our efforts toward defined and *specific* goals (other than the vague "we need a new site!"). Thanks to all for your patience! In the mean time, two documents I would like to work on (and could frankly use some help with like *now*), are: http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts http://trac.macosforge.org/projects/macports/wiki/TracTicketing The first one was edited not long ago, but I haven't had a chance to go over it. In any case, the installation page we had back on the OpenDarwin site was pretty good and I think we could re-use some of the material that was there (in svn, trunk/www/getdp). The second one deals with the guidelines for filing trac tickets, and needs revising in view of our new roadmap and milestones; I promised I'd deliver that document a couple of weeks ago but I've been so up to my neck that I only managed to complete the 1.4.0 release just some days ago! If you, Sean, or anyone else reading is willing to help me with these two docs, at least, don't hesitate to contact me to coordinate work. Thanks in advance for your offer! Regards to all and thanks again for your patience and for coping until now with out *cough* excuse *cough* for a website! -jmpp
On 2007-04-07 18:22:18 -0400, Juan Manuel Palacios <jmpp@macports.org> said:
On Apr 6, 2007, at 2:45 PM, Sean Fulton wrote:
That's all fine and good but I want jump in the pile-on and say that the site and documentation need some serious attention. Having outdated docs in SVN is less than ideal.
Now that 1.4 is out will there be some effort to providing useful documentation? Do the project leads need volunteers to help? I'm willing.
At first I thought about saying "Ooohh, we so *totally* need volunteers to clean-up/improve our site!!", but then I asked myself "improve *how* and *what* exactly?"
I think it's pretty clear to everyone that we need a major website and documentation overhaul (that said with my MacPorts Manager hat on!), so I'd say that before we do any minor and possibly random rearrangements and/or cleanups here and there, one thing we need to do, as a team and as openly as possible, is to discuss what we would like to see in a new website (including everything: welcoming portal, downloads section, documentation section, headlines, trac integration, per ports page, etc...).
I've been thinking about bootstrapping this discussion and putting forth some initial ideas into the mix, and maybe even asking (inviting) some of the WebKit folks to give us a hand with the redesign (they obviously have a thing for websites ;-); but other than that, we as a team don't have much of a roadmap with respect to our site, admittedly and unfortunately. I'll bring the subject up with the other managers and MacOSForge admin personnel to at least get an initial feeling of what we can do (not only resource wise but also with respect to some guidelines we have to stick by), and will post again on the subject when I get a clearer idea. I think it's wise to ask everyone with either a dire stray need for a new site (because the current one sucks!) and/or the appreciated willingness to help, to wait until such time for us to better coordinate all our efforts toward defined and *specific* goals (other than the vague "we need a new site!"). Thanks to all for your patience!
In the mean time, two documents I would like to work on (and could frankly use some help with like *now*), are:
http://trac.macosforge.org/projects/macports/wiki/InstallingMacPorts http://trac.macosforge.org/projects/macports/wiki/TracTicketing
The first one was edited not long ago, but I haven't had a chance to go over it. In any case, the installation page we had back on the OpenDarwin site was pretty good and I think we could re-use some of the material that was there (in svn, trunk/www/getdp). The second one deals with the guidelines for filing trac tickets, and needs revising in view of our new roadmap and milestones; I promised I'd deliver that document a couple of weeks ago but I've been so up to my neck that I only managed to complete the 1.4.0 release just some days ago!
If you, Sean, or anyone else reading is willing to help me with these two docs, at least, don't hesitate to contact me to coordinate work. Thanks in advance for your offer!
Regards to all and thanks again for your patience and for coping until now with out *cough* excuse *cough* for a website!
Redesign the whole site would definitely require planning and discussion. I feel like the documentation issue is more immediate. Right now it doesn't exist except for anyone knowledgeable enough to delve into the SVN repository. For a start I would like to see all of the old docs dumped into the Wiki so people have access to them and some could hack on them. I've found there are parts that I would have edited as I was learning/using DarwinPorts/MacPorts. I'll help where I can. Sean p.s. my account is messed up. I tried to update it as the macosforge site tells you but I still cannot access 'My Account' profile. And, is the Wiki open to editing by anyone with an account? I don't see any option to edit pages. The only thing I can seem to do is file tickets.
On Apr 8, 2007, at 14:00, Sean Fulton wrote:
Redesign the whole site would definitely require planning and discussion. I feel like the documentation issue is more immediate. Right now it doesn't exist except for anyone knowledgeable enough to delve into the SVN repository.
I have tried and failed. I have a working copy of the trunk. But the documentation is not in the www directory. Instead, it appears to be in the doc directory, in docbook-xml format. To build the HTML pages apparently requires that I install the docbook-xsl port. Ok, but even then, I can't build it: $ cd doc/guide $ make xmllint --xinclude --noout "xml/guide.xml" http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:80: element include: XInclude error : could not load xml/portfiles/details.xml, and no fallback was found http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:113: element include: XInclude error : could not load xml/project/submission.xml, and no fallback was found make: *** [check] Error 1 $ Long story short: I'm gonna read the docs using the Internet Archive from now on: http://web.archive.org/web/20060427120406/http:// darwinports.opendarwin.org/docs/
For a start I would like to see all of the old docs dumped into the Wiki so people have access to them and some could hack on them. I've found there are parts that I would have edited as I was learning/using DarwinPorts/MacPorts.
Do we want to do that? Admittedly wikis are easier to edit. But wasn't the docbook format chosen for a reason? To those who remember: What was that reason? Does it still apply?
p.s. my account is messed up. I tried to update it as the macosforge site tells you but I still cannot access 'My Account' profile. And, is the Wiki open to editing by anyone with an account? I don't see any option to edit pages. The only thing I can seem to do is file tickets.
I am under the impression that anyone should be allowed to edit wiki pages. When I access wiki URLs beginning with https and log in with my macports account, there is an Edit This Page button at the bottom of each.
Ryan Schmidt <ryandesign@macports.org> on Monday, April 9, 2007 at 2:22 AM -0800 wrote:
Redesign the whole site would definitely require planning and discussion. I feel like the documentation issue is more immediate. Right now it doesn't exist except for anyone knowledgeable enough to delve into the SVN repository.
I have tried and failed. I have a working copy of the trunk. But the documentation is not in the www directory. Instead, it appears to be in the doc directory, in docbook-xml format. To build the HTML pages apparently requires that I install the docbook-xsl port. Ok, but even then, I can't build it:
$ cd doc/guide $ make xmllint --xinclude --noout "xml/guide.xml" http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:80: element include: XInclude error : could not load xml/portfiles/details.xml, and no fallback was found http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT ^ xml/guide.xml:113: element include: XInclude error : could not load xml/project/submission.xml, and no fallback was found make: *** [check] Error 1 $
I'm not sure why it chokes on the xincludes. I've been writing in DocBook lately, but I use the XMLMind XML editor, called XXE for short. It is a WYSIWG editor. It seems to have no trouble handling the xincludes and opens it all up in the editor.
Long story short: I'm gonna read the docs using the Internet Archive from now on:
http://web.archive.org/web/20060427120406/http:// darwinports.opendarwin.org/docs/
For a start I would like to see all of the old docs dumped into the Wiki so people have access to them and some could hack on them. I've found there are parts that I would have edited as I was learning/using DarwinPorts/MacPorts.
Do we want to do that? Admittedly wikis are easier to edit. But wasn't the docbook format chosen for a reason? To those who remember: What was that reason? Does it still apply?
I think the advantages are: -A defined document structure is enforced. -Easy transformation to HTML, PDF, etc. -The format of the document is abstracted from the content. So style and format decisions do not need to be made when writing. -Format and style decisions for HTML (transformed from XML DocBook) are made separately via CSS, and so style changes are applied globally so that style consistency is enforced. But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know. I wonder if an unstructured document that has no enforcement of structure or style will be better in the end. But using an XML DocBook editor to edit and modify the current docs isn't that hard, but, similar to what Juan said, not enough time has been spent on deciding the content we want to have in our docs. If we had people contributing text of new docs, we could think about the technology to use it. But people want to be able to input text on their own into the Wiki and want to decide the content later. I wonder how well that will work for us in the end, but I've not had experience with a free-for-all wiki documentation. If it turns out an editor or supervisor for docs is needed anyway, which seems likely to me, then the advantages of a Wiki may not be as much as supposed and it may be more difficult to manage it all.
p.s. my account is messed up. I tried to update it as the macosforge site tells you but I still cannot access 'My Account' profile. And, is the Wiki open to editing by anyone with an account? I don't see any option to edit pages. The only thing I can seem to do is file tickets.
I am under the impression that anyone should be allowed to edit wiki pages. When I access wiki URLs beginning with https and log in with my macports account, there is an Edit This Page button at the bottom of each.
It is my understanding that right now only a few people can edit. I can and you can, but apparently we have higher powers than the average user. Mark
On Apr 9, 2007, at 10:17, markd@macports.org wrote:
But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know.
I've come across a number of projects using wiki documentation lately. Lacking any centralized editing, it tends to vary wildly in quality, substance, and style. Information is poorly organized and difficult to find, and documentation is often duplicated. Maybe my experiences aren't a sufficiently representative example, but I've been left with a very poor impression of open source wiki documentation. -landonf
On Apr 9, 2007, at 02:22, Ryan Schmidt wrote:
$ cd doc/guide $ make xmllint --xinclude --noout "xml/guide.xml" http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT
make xhtml or make html Try adding --nonet to the xsltproc parameters
On Apr 9, 2007, at 1:46 PM, Landon Fuller wrote:
On Apr 9, 2007, at 10:17, markd@macports.org wrote:
But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know.
I've come across a number of projects using wiki documentation lately. Lacking any centralized editing, it tends to vary wildly in quality, substance, and style. Information is poorly organized and difficult to find, and documentation is often duplicated.
Maybe my experiences aren't a sufficiently representative example, but I've been left with a very poor impression of open source wiki documentation.
-landonf
I'm, personally, not opposed to Docbook but think that Wiki documentation would happen a lot quicker. It all depends on whether there is anyone putting significant effort into documentation. If there is a documentation lead who keeps on top of it and manages changes, submissions, etc., Docbook is a logical choice. If documentation is taking a back seat, I think the Wiki is the best alternative to no documentation. Let us users share what we glean from the mailing-lists and using MacPorts in the absence of documentation by the people who built it. Sean
On Apr 9, 2007, at 1:46 PM, Landon Fuller wrote:
On Apr 9, 2007, at 10:17, markd@macports.org wrote:
But the disadvantage, as opposed to a Wiki, is that joe user can't make changes to the docs. And that is what people want. Although I wonder if we have Joe user contributing to the docs if it will really be better. It may be, I just don't know.
I've come across a number of projects using wiki documentation lately. Lacking any centralized editing, it tends to vary wildly in quality, substance, and style. Information is poorly organized and difficult to find, and documentation is often duplicated.
Maybe my experiences aren't a sufficiently representative example, but I've been left with a very poor impression of open source wiki documentation.
-landonf
One solution to this problem I was thinking about is a middle ground between requiring coding skills to allow you to edit a doc (if you have them, logic tells me you already hold a macports commit bit and therefore can edit the Wiki already.... or are not afraid to delve into Dockbook sources ;-) and giving access to everyone (open season on our Wiki, anyone can edit): said middle ground could be a WIKI_EDITING trac permission setting (or whatever to that effect) we could hand selectively to those who've proven an at least acceptably high knowledge of MacPorts; said people need not be skilled enough to commit to our repo and/or know how to edit docbook sources, but should at least be knowledgeable enough to know what they're talking about when writing documentation. We could receive nominations for such people and judge based on their activity on our lists, for instance, and maybe even the Wiki editor status could be seen as a step before gaining commit access to the repo (though not necessarily). Thoughts? -jmpp
On Apr 9, 2007, at 12:55, Landon Fuller wrote:
On Apr 9, 2007, at 02:22, Ryan Schmidt wrote:
$ cd doc/guide $ make xmllint --xinclude --noout "xml/guide.xml" http://www.oasis-open.org/docbook/xml/4.2/dbpoolx.mod:99: parser error : Content error in the external subset <!ENTIT
make xhtml
Thank you, that seemed to work.
or make html
Try adding --nonet to the xsltproc parameters
I didn't try that. Some error messages were still printed by "make xhtml" but at least it completed and did build the documentation.
participants (5)
-
Juan Manuel Palacios
-
Landon Fuller
-
markd＠macports.org
-
Ryan Schmidt
-
Sean Fulton