Re: [gentoo-dev] Projects and simple guides
On Tue, 10 Jan 2006 15:12:27 -0600 Lance Albertson [EMAIL PROTECTED] wrote: | Last I knew, its not a simple task for generating those nice looking | html pages that ciaranm made a while back for the developer docs. | When I asked him about (he can probably provide more detail), It took | a lot of processing time and wasn't that scalable. Now, I'm not sure | if anything has changed since then. If you're using docutils, then yes, it's reaallly slow. I've got a (very fast) parser that handles a decent subset of the RST spec written, but getting it converted to be usable in a general kind of way isn't too high up my list of priorities... The thing is... If you're trying to do RST - GuideXML, you'll run into all kinds of weirdness because of the GuideXML heading structure. You'll also run into a load more weirdness because about half of the GLEPs currently massively abuse blockquotes (in all but one case accidentally). See, this is a list in RST: * one * two And this is a list inside a blockquote: * one * two Very easy to screw up, especially since docutils goes to great lengths to create output even if the input is highly weird. My own parser moans on anything like that -- it disallows most nested structure markup -- which means it's useless on most GLEPs unless someone goes through and does some serious whitespace cleanups... -- Ciaran McCreesh : Gentoo Developer (King of all Londinium) Mail: ciaranm at gentoo.org Web : http://dev.gentoo.org/~ciaranm signature.asc Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Lance Albertson wrote: | Donnie Berkholz wrote: | |Lance Albertson wrote: || What if instead of having proj/en we did herd/en on www? Of course, that || doesn't help the whole GuideXML is hard bit. I like the idea of using || RST, but it doesn't seem very scalable at this time. Maybe, instead of || that, we created some kind of development site for herds (maybe || herds.g.o). Could be a place where herds put up status updates, specific || docs, draft docs, etc. Once things get established on that site, docs || could get moved to GDP if it were logical to do. | |Really every herd should be either part of a project or in the process |of creating a new one for themselves by now. There's no excuse, since |the block on creating new projects disappeared. | | | The question I ask is ... does every herd have a project it fits under? | I doubt it. And if it doesn't, is it really considered a project? Or is | that just a generic name given now? I guess a see a distinction between | herds and projects that our current documentation url layout doesn't | cover it well. To me, it should have its own herd/fooherd layout | (example being www.gentoo.org/herd/en/netmon). Otherwise you're going to | confuse our users into thinking that herds are projects when they're | really just herds. Granted, some herds may be just a project, but I'm | mainly after the herds that have no real project to fit under. | | I understand the block was lifted for projects, but that doesn't mean | herds should all should fit underneath proj/. I agree. What I meant is that herds should be grouping together to form new projects if they don't fit in an existing one; not that they should create one project per herd. | I think we should open up | a similar space just for herds. I disagree -- they should all be able to fit into some project. Thanks, Donnie -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.2 (GNU/Linux) iD8DBQFDw2znXVaO67S1rtsRAo7hAKC2yYmsZdDV0AUxf8H8ucXdI4GH8wCgzrIm itfdvfs5OSPLiEj13RmMxzs= =BdR+ -END PGP SIGNATURE- -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
Donnie Berkholz wrote: Sven Vermeulen wrote: | We have already received many bugs for documentation in /proj/* which is | not GDPs. I had no issue with this as I hoped this would be a transient | state where the documentation is eventually handed over to the GDP so that | both the project /and/ GDP can further maintain the documents. Seems like what would be useful is a metadata.xml-type thing for guides, so they're assigned properly. That's only a Bugzilla issue. When user finds a bug somewhere under /proj/en, the natural way is to consider it an issue in documentation for users, hence it got assigned to docs-team. There's already a bug opened [1] waiting for the final decision. [1] https://bugs.gentoo.org/show_bug.cgi?id=115924 Cheers, -jkt -- cd /local/pub more beer /dev/mouth signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
On Tue, 2006-01-10 at 01:17 -0600, Lance Albertson wrote: I understand the block was lifted for projects, but that doesn't mean herds should all should fit underneath proj/. I think we should open up a similar space just for herds. I think that would be a wonderful idea. What would we do about herds that are a project? Simply throw in a redirect under the herd name to the project name? -- Chris Gianelloni Release Engineering - Strategic Lead x86 Architecture Team Games - Developer Gentoo Linux signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] Projects and simple guides
Chris Gianelloni said: Really, I think that the number of bugs the GDP gets is probably fairly minimal for project-based documentation. Perhaps we could have something added to the project dtd that adds a little blurb at the bottom to file bugs for project documentation against the project itself? I really don't know if that would help or not, but it is an idea. The amount of bugs isn't the problem, but it does serve as a warning event to show the user how fragmented a project goal can be. In this case, not even all documentation is handled by the documentation team. Wkr, Sven Vermeulen -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
Chris Gianelloni wrote: On Tue, 2006-01-10 at 01:17 -0600, Lance Albertson wrote: I understand the block was lifted for projects, but that doesn't mean herds should all should fit underneath proj/. I think we should open up a similar space just for herds. I think that would be a wonderful idea. What would we do about herds that are a project? Simply throw in a redirect under the herd name to the project name? Unless they already reside inside the /proj level, I don't want to get into the habit of managing a bunch of redirects. The key thing here is that we have a clear place to look for such herds. If they are a project, then keep them in the project area. -- Lance Albertson [EMAIL PROTECTED] Gentoo Infrastructure | Operations Manager --- GPG Public Key: http://www.ramereth.net/lance.asc Key fingerprint: 0423 92F3 544A 1282 5AB1 4D07 416F A15D 27F4 B742 ramereth/irc.freenode.net signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
Grant Goodyear wrote: [Tue Jan 10 2006, 11:09:15AM EST] As an aside, it's ciarnanm has already put work in on developing an RST to guidexml converter, so I wouldn't worry too much about RST not scaling. Could that be used dynamically on the server? The last time I was familiar with the gentoo.org server, it was running axkit and dynamically generating HTML from the GuideXML. Is it a relatively simple matter to support .rst files in the same manner? A related question: How hard would it be to enable the dynamic generation for dev.gentoo.org/~users? That would make development of RST or GuideXML documents *much* simpler, since we could just work on the file in our public_html and test render it by accessing through a web browser. Regards, Aron -- Aron Griffis Gentoo Linux Developer pgpF7KHOmWDtC.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Hi Donnie, On 1/10/06, Donnie Berkholz [EMAIL PROTECTED] wrote: -BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Donnie Berkholz wrote: | I don't want to get into the habit of inconsistency and finding herds in | two different locations. To clarify, add an either onto the end of that. | Thanks, | Donnie Don't you think that maybe you're trying to bash square pegs into round holes just for the sake of some sort of order that perhaps doesn't actually benefit anyone at all? Where did the requirement that a herd has to be part of a larger project come from? GLEP 39's crystal clear that we don't need a project to cover every peice of work that Gentoo devs do. Herds aren't even mentioned in there :) Why not just let herds carry on creating entries under /proj/en/? If they're part of a larger project, that project can just link to the herd's page. Our directory structure doesn't have to reflect a biological classification tree :) Best regards, Stu -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
On Monday 09 January 2006 03:14, Marius Mauch wrote: Find a nice place in www.gentoo.org/proj/ Okay that's what I try to do most of the time, in this specific case, I'm probably going to ask for space to qa project (as fixing --as-needed problems or parallel make issues and such is imho QA-related). This still does not resolve issues for other things like the quilt guide I tried to start writing (but then I'm not so good at explain the user/dev part of it). But at least I'll probably have time to spend on the other stuff for a while if Sven allows me :) -- Diego Flameeyes Pettenò - http://dev.gentoo.org/~flameeyes/ Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE pgpxkXHgVjPB5.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Brian Harring wrote:[Sun Jan 08 2006, 09:16:36PM EST] Regardless, (imo) it's already been laid out why guideXML'ifying everything doesn't totally work. Three reasons... A) bit of work required just to jot down a quick list of this is broke, fix it that's going to be thrown out 2 weeks down the line. I noticed Ciaran has been using RST for GLEP 42. I wonder if it would be a good alternative to guideXML in general. http://docutils.sourceforge.net/rst.html I realize this doesn't address the *rest* of what you said, though... Regards, Aron -- Aron Griffis Gentoo Linux Developer pgpz1VyIiCw8i.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
On Mon, 9 Jan 2006 09:34:22 -0500 Aron Griffis [EMAIL PROTECTED] wrote: Brian Harring wrote: [Sun Jan 08 2006, 09:16:36PM EST] Regardless, (imo) it's already been laid out why guideXML'ifying everything doesn't totally work. Three reasons... A) bit of work required just to jot down a quick list of this is broke, fix it that's going to be thrown out 2 weeks down the line. I noticed Ciaran has been using RST for GLEP 42. I wonder if it would be a good alternative to guideXML in general. http://docutils.sourceforge.net/rst.html I realize this doesn't address the *rest* of what you said, though... I agree. These little 'howtos' are potentially very short, and guideXML would be overkill. RST is absolutely perfect for this kind of thing: quick and easy to write, powerful, and legible in raw form. It's also easily converted to any number of other formats. A new CVS repository containing these little howtos that is accessible with viewcvs would be perfect, if you ask me. There would be proper version control on the files and they would be read/write for developers and read-only for users (otherwise the potential of vandalism etc. is too high). This is, in my opinion, how things should be for these simple developer guides. I'd also propose that these things are listed in a flat directory hierarchy, more or less. I'd rather the names of the files were prefixed with the project/herd name and then dumped in the same directory.It would encourage 'reading around' a bit (you know, like when you look up a word in a dictionary and end up learning another few words by accident). This can only be a good thing (I'll admit that, say, a documentation developer stumbling across the Gentoo/MIPS stabilisation criteria is not in reality that useful useful, but in the majority of cases this rule holds true). The whole wiki-for-everything idea really annoys me. It forces a web browser on me, and this is particularly naff when it comes to editing. It's also really bland and boring, and completely unoriginal. They're also hard to navigate. If I was going to write one of these guides I'd rather put a .txt on my devspace than bother with the devwiki. I still haven't fixed the other two points Brian mentioned, but I don't really think they're all that serious. If a user sees an omission, he can drop a mail to the guy who wrote the guide. There's really no reason to file bugs for anything like this. Allowing universal r/w is asking for vandalism. As for the third point -- concurrency -- this is exactly what any VCS is supposed to fix. We live with it with the tree's CVS, I'm sure we can live with it for this. I guess it's also important to distinguish what constitutes a little development 'howto' for some common task, rather than a full-on GDP guide. -- Tom Martin, http://dev.gentoo.org/~slarti AMD64, net-mail, shell-tools, vim, recruiters Gentoo Linux signature.asc Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Sending this to the ml, tom already has heard the reasons but throwing them out for others to comment on... On Mon, Jan 09, 2006 at 04:47:57PM +, Tom Martin wrote: I realize this doesn't address the *rest* of what you said, though... snip These little 'howtos' are potentially very short, and guideXML would be overkill. RST is absolutely perfect for this kind of thing: quick and easy to write, powerful, and legible in raw form. It's also easily converted to any number of other formats. Agreed. A new CVS repository containing these little howtos that is accessible with viewcvs would be perfect, if you ask me. There would be proper version control on the files and they would be read/write for developers and read-only for users (otherwise the potential of vandalism etc. is too high). This is, in my opinion, how things should be for these simple developer guides. disagree. :) Note my comments about allowing non gentoo personnel to modify the docs. I'm not minting half devs just so they can do some doc work, nor is it efficient for trusted devs to be passing patches through me just because they haven't yet been around long enough where we mint 'em. The whole wiki-for-everything idea really annoys me. It forces a web browser on me, and this is particularly naff when it comes to editing. It's also really bland and boring, and completely unoriginal. Note that what's being pushed here is the desire for a faster model of doc developing; GDP/guidexml docs are good for long term stable docs. They suck royally however, if we're talking about developmental docs for portage where things move quickly. Less work required to maintain the documentation, higher chance the docs will actually be up to date/maintained. Note that's my opinion, I don't dislike guidexml, I just prefer to not dink around with it for docs that are going to be rapidly changing. I still haven't fixed the other two points Brian mentioned, but I don't really think they're all that serious. If a user sees an omission, he can drop a mail to the guy who wrote the guide. There's really no reason to file bugs for anything like this. We're not talking about a guide here- two scenarios. flameeyes rapid development of docs, improving the quality- area to hash out the doc before slapping it up in official docs (and no, labelling it unofficial doesn't fly when we're talking about initial hammering out of the doc). Essentially, a chalkboard/whiteboard for projects- communal scratchpad of what the current issues are (and I mean *current*, that day), proposals for apis, use scenarios, rough design documents. We could (and do) do this via devspace, but that suffers the exact issue I'm after addressing- not everyone involved can modify it (for devspace, only one person can modify it). Allowing universal r/w is asking for vandalism. As for the third point -- concurrency -- this is exactly what any VCS is supposed to fix. We live with it with the tree's CVS, I'm sure we can live with it for this. Where exactly did I ask for universal r/w? I've seen a lot of args against this based upon joe idiot will screw up the page. What I'm after is non gentoo personnel capable of handling the docs- does that mean everyone? No. It means people not minting people just so we can have them do a bit of doc work, essentially, nuking the overhead. Again, vcs is worthless if you don't have access to it. Non gentoo folks do not have access to the vcs, thus we're right back to my point for why a wiki is useful- we don't have to mint a couple dozen part time contributors as devs just so they can do their work. Proposals/alternatives thus far are basically reinventing wiki's, just slower. That's kind of a sign that people dislike wiki software they've seen- I've yet to see anyone level arguement against the model of doc development I'm after however. So... if the core need isn't an issue, wth should we reinvent the wheel and create our own wiki analog? ~harring pgpAknTOSAknI.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
On Mon, 9 Jan 2006 16:47:57 + Tom Martin [EMAIL PROTECTED] wrote: On Mon, 9 Jan 2006 09:34:22 -0500 Aron Griffis [EMAIL PROTECTED] wrote: Brian Harring wrote:[Sun Jan 08 2006, 09:16:36PM EST] Regardless, (imo) it's already been laid out why guideXML'ifying everything doesn't totally work. Three reasons... A) bit of work required just to jot down a quick list of this is broke, fix it that's going to be thrown out 2 weeks down the line. I noticed Ciaran has been using RST for GLEP 42. I wonder if it would be a good alternative to guideXML in general. http://docutils.sourceforge.net/rst.html I realize this doesn't address the *rest* of what you said, though... I agree. These little 'howtos' are potentially very short, and guideXML would be overkill. RST is absolutely perfect for this kind of thing: quick and easy to write, powerful, and legible in raw form. It's also easily converted to any number of other formats. A new CVS repository containing these little howtos that is accessible with viewcvs would be perfect, if you ask me. (big snip) ... And then Flameeyes showed me MoinMoin. It understands RST and can also do XMLRPC. Best of all worlds. -- Tom Martin, http://dev.gentoo.org/~slarti AMD64, net-mail, shell-tools, vim, recruiters Gentoo Linux signature.asc Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Diego 'Flameeyes' Pettenò wrote: [Sun Jan 08 2006, 11:59:40AM CST] I originally thought of putting it on my devspace, but using GuideXML there is a bit tricky, at least for me (as xsltproc seems to refuse working on the pure xml directly). I actually prefer devspace for these sorts of docs. Every dev has their own space for that sort of thing, and they can use whatever easy-to-manage doc producing system that they want (within reason). Instead of fixing that problem, I think it would be better to fix the xsltproc issues you're having instead. If you'll post what's happening to your doc, perhaps one of our trusty doc folks can help you out. So I was thinking if we had a way to put some how to fix guides somewhere, on the lines of the ones written by soalr and vapier for hardened. A part the --as-needed thing, it might also be useful to put something about how to solve parallel make issues and similar things that are tricky but usually just requires little knowledge of tricks. Again, I like devspace for these things. Of course, particularly useful docs would likely be adopted by the GDP (with the permission of the author, of course). -g2boojum- -- Grant Goodyear Gentoo Developer [EMAIL PROTECTED] http://www.gentoo.org/~g2boojum GPG Fingerprint: D706 9802 1663 DEF5 81B0 9573 A6DC 7152 E0F6 5B76 pgppVuia9qUyz.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Grant Goodyear wrote: Again, I like devspace for these things. Of course, particularly useful docs would likely be adopted by the GDP (with the permission of the author, of course). Thinking about legal issues (and about tracking all contributors among developers) - please use CC-BY-SA [1] for your docs. [1] http://creativecommons.org/licenses/by-sa/2.5 Cheers, -jkt -- cd /local/pub more beer /dev/mouth signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
Grant Goodyear wrote: Diego 'Flameeyes' Pettenò wrote: [Sun Jan 08 2006, 11:59:40AM CST] I originally thought of putting it on my devspace, but using GuideXML there is a bit tricky, at least for me (as xsltproc seems to refuse working on the pure xml directly). I actually prefer devspace for these sorts of docs. Every dev has their own space for that sort of thing, and they can use whatever easy-to-manage doc producing system that they want (within reason). Instead of fixing that problem, I think it would be better to fix the xsltproc issues you're having instead. If you'll post what's happening to your doc, perhaps one of our trusty doc folks can help you out. If there is something I can do on toucan to make things better, let me know. I haven't heard much from anyone that something is broke about it. I could setup gorg on toucan or something to make things better for such things. Just create a bug so I can put it on my todo list. -- Lance Albertson [EMAIL PROTECTED] Gentoo Infrastructure | Operations Manager --- GPG Public Key: http://www.ramereth.net/lance.asc Key fingerprint: 0423 92F3 544A 1282 5AB1 4D07 416F A15D 27F4 B742 ramereth/irc.freenode.net signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
On Mon, 9 Jan 2006 18:11:42 +0100 Diego 'Flameeyes' Pettenò [EMAIL PROTECTED] wrote: And IIRC ciaranm said it took quite a while to render the devmanual from RST to HTML, would be difficult to sync hourly then. The devmanual has an an enormous number of links, citations and cross references. I'd imagine that's what really takes time to generate. For things like this, it would be very fast. -- Tom Martin, http://dev.gentoo.org/~slarti AMD64, net-mail, shell-tools, vim, recruiters Gentoo Linux signature.asc Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
On Monday 09 January 2006 21:04, Tom Martin wrote: The devmanual has an an enormous number of links, citations and cross references. I'd imagine that's what really takes time to generate. For things like this, it would be very fast. Might be good to test moinmoin's RST support then. -- Diego Flameeyes Pettenò - http://dev.gentoo.org/~flameeyes/ Gentoo/ALT lead, Gentoo/FreeBSD, Video, AMD64, Sound, PAM, KDE pgpVQ19lNU7hY.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
On Sun, Jan 08, 2006 at 06:45:01PM +, Luis Medinas wrote: We could start a public wiki displaying all herds and projects. It would be great to add some low level docs, herds/project goals, ideas and so. Even the users could be allowed to edit and share information. I would personally welcome additional documentation, but if we're going to add an official Wiki for Gentoo, we're basically splitting the documentation development on many sides. What used to be a (forced) monopoly for GuideXML becomes a set of GuideXML, RST and Wiki. Although I have indeed read that the goal of the documents differ, we are placing a boundary on what GDP should do and shouldn't. We have already received many bugs for documentation in /proj/* which is not GDPs. I had no issue with this as I hoped this would be a transient state where the documentation is eventually handed over to the GDP so that both the project /and/ GDP can further maintain the documents. A wiki is nice, but don't forget that it only allows for online documentation editing. I am one of those devs who develops his documentation mostly off-line. There is also no quality assurance over a wiki and not that many wikis have decent versioning tools (or they have them but they're really awkward to use). The Java team already uses the gentoo-wiki.com infrastructure, indeed an unofficial wiki for official documentation. Wkr, Sven Vermeulen -- Gentoo Foundation Trustee | http://foundation.gentoo.org Gentoo Council Member The Gentoo Projecthttp://www.gentoo.org pgp9i29yzFCoL.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Lance Albertson wrote: | What if instead of having proj/en we did herd/en on www? Of course, that | doesn't help the whole GuideXML is hard bit. I like the idea of using | RST, but it doesn't seem very scalable at this time. Maybe, instead of | that, we created some kind of development site for herds (maybe | herds.g.o). Could be a place where herds put up status updates, specific | docs, draft docs, etc. Once things get established on that site, docs | could get moved to GDP if it were logical to do. Really every herd should be either part of a project or in the process of creating a new one for themselves by now. There's no excuse, since the block on creating new projects disappeared. | Now that leaves us to unofficial docs from users. I'm not sure where to | put that. A public wiki poses a whole slew of issues I don't think we | have enough staff to manage. But relying on gentoo-wiki isn't exactly | the best avenue either. Having a site like this is like having another | 'team' similar to the forums trying to maintain order/facts. There needs | to be another solution that doesn't require as much effort on our part. | I sadly can't think of an answer. I guess the real question is, is this | that much of a problem/issue? Are there any wikis with the same kind of spam-protection that a lot of blogging software has, such as the crazy-looking picture you have to type the word from, and required registration with a valid email address? The combination of those two would do a lot to deter automated spamming, although a determined person could still do damage if they're sitting in front of the computer. Some wiki's also support ACLs, which could help in this respect. For example, xorg.freedesktop.org has some pages that are immutable and can only be edited by a few people. Thanks, Donnie -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.2 (GNU/Linux) iD8DBQFDw1qBXVaO67S1rtsRAsGhAJ4yjLfL7pk5hqCQgkKeoB7KQ1bd/QCggRx/ u4bFgzcQEHAZKYcOac3+3d4= =F9Jt -END PGP SIGNATURE- -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
On Sun, Jan 08, 2006 at 06:59:40PM +0100, Diego 'Flameeyes' Petten? wrote: GDP might be the place where to put them, but as they are mainly developer-oriented, they might be better accessed directly by devs (at least for the first steps until they are drafts). What people think about this? Devwiki -- Renat Lumpau all things web-apps GPG key id #C6A838DA on http://pgp.mit.edu Key fingerprint = 04AF B5EE 17CB 1000 DDA5 D3FC 1338 ADC2 C6A8 38DA pgpwbY2PT4lBn.pgp Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
Brian Harring wrote: On Sun, Jan 08, 2006 at 06:07:48PM +, Renat Lumpau wrote: On Sun, Jan 08, 2006 at 06:59:40PM +0100, Diego 'Flameeyes' Petten? wrote: GDP might be the place where to put them, but as they are mainly developer-oriented, they might be better accessed directly by devs (at least for the first steps until they are drafts). What people think about this? Devwiki Devwiki is effectively inaccesable to non gentoo folks (whether in access, or in navigating the beast), thus it's a no go. Any docs generated should be googable imo. If they are needing an initial place to start things off before they go official, then the devwiki is a perfect place. Once they are ready to be consumed by the other folks, they should be placed on www.g.o somewhere. -- Lance Albertson [EMAIL PROTECTED] Gentoo Infrastructure | Operations Manager --- GPG Public Key: http://www.ramereth.net/lance.asc Key fingerprint: 0423 92F3 544A 1282 5AB1 4D07 416F A15D 27F4 B742 ramereth/irc.freenode.net signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
Luis Medinas wrote: On Sun, 2006-01-08 at 10:31 -0800, Brian Harring wrote: On Sun, Jan 08, 2006 at 06:07:48PM +, Renat Lumpau wrote: On Sun, Jan 08, 2006 at 06:59:40PM +0100, Diego 'Flameeyes' Petten? wrote: GDP might be the place where to put them, but as they are mainly developer-oriented, they might be better accessed directly by devs (at least for the first steps until they are drafts). What people think about this? Devwiki Devwiki is effectively inaccesable to non gentoo folks (whether in access, or in navigating the beast), thus it's a no go. Any docs generated should be googable imo. We could start a public wiki displaying all herds and projects. It would be great to add some low level docs, herds/project goals, ideas and so. Even the users could be allowed to edit and share information. Anything like that will need to be approved by the GDP and a GLEP. Creating any sort of public wiki will basically halt the efforts of the GDP which I'd rather not do. Not to mention deciding who would be monitoring it and such (allocating people's time to it). I'm opposed to any public wiki until the GDP states their opinion on it. Its their area and I don't want to take it away from them. -- Lance Albertson [EMAIL PROTECTED] Gentoo Infrastructure | Operations Manager --- GPG Public Key: http://www.ramereth.net/lance.asc Key fingerprint: 0423 92F3 544A 1282 5AB1 4D07 416F A15D 27F4 B742 ramereth/irc.freenode.net signature.asc Description: OpenPGP digital signature
Re: [gentoo-dev] Projects and simple guides
On Sun, 2006-01-08 at 12:54 -0600, Lance Albertson wrote: Devwiki is effectively inaccesable to non gentoo folks (whether in access, or in navigating the beast), thus it's a no go. Any docs generated should be googable imo. We could start a public wiki displaying all herds and projects. It would be great to add some low level docs, herds/project goals, ideas and so. Even the users could be allowed to edit and share information. Anything like that will need to be approved by the GDP and a GLEP. Creating any sort of public wiki will basically halt the efforts of the GDP which I'd rather not do. Not to mention deciding who would be monitoring it and such (allocating people's time to it). I'm opposed to any public wiki until the GDP states their opinion on it. Its their area and I don't want to take it away from them. Indeed it's GDP area but to expose project goals, status and low level docs isn't even related with GDP. We can't maintain the high level of docs like GDP does and it's not even your goal. I think the public wiki idea will improve the communication between devs and users, add goals and show the status of projects. IMO GDP can't do much in this area simply because they don't have much to do about this and they have of course high level of docs to maintain. -- Luis Medinas [EMAIL PROTECTED] http://dev.gentoo.org/~metalgod Gentoo Linux Developer: AMD64,Printing,Media-Optical,Sound -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
On Sun, 2006-01-08 at 13:31 -0600, Lance Albertson wrote: Indeed it's GDP area but to expose project goals, status and low level docs isn't even related with GDP. We can't maintain the high level of docs like GDP does and it's not even your goal. I think the public wiki idea will improve the communication between devs and users, add goals and show the status of projects. IMO GDP can't do much in this area simply because they don't have much to do about this and they have of course high level of docs to maintain. I had thought about creating some kind of a site like this, but not necessarily in a wiki form. I don't like the idea of letting users add random docs. There's too much room for error and how do you deal with accountability? There has to be a developer who either will take the time to maintain it or accept responsibility for any errors it may have. I like the idea of having an area for herds to keep track of their internal thing, but I fear it will just end up replacing what the GDP (and our www site) does. Its too easy for them to just start adding docs there instead of on www because its 'too hard' to deal with guidexml. Like i said GDP maintain High Level Docs i think no one want's to replace that. Herds docs will not replace GDP. Even if that's for somehow happen it could be easy backported to GDP maintaining an High Level doc. A few months back Diego Flameeyes started writing maintainer docs for some applications, X team started their own docs about modular X, amd64 team does have their docs and it doesn't have anything to do with GDP or will replace them. An example for this is the AMD64 FAQ that is part of GDP and all writen by AMD64 team. If the issue here is guidexml, lets figure out the problem. We need to define what exactly is the problem before we decide on an implementation. Is the problem that there's no central place for herds to put updates/goals/etc? Is the problem that there's no easy way for users to submit new docs for people to use? Is the problem that guidexml hampers development time with regard to creating docs and you wish to have a better/easier way to create such docs? Indeed guidexml isn't a fast method to write information but we should keep it for high level docs of course. Simply saying 'we need a public wiki' is great an all, but I'd rather ask 'What problem(s) does the wiki solve' before we even get farther. There might be better ways to solving the problem other than putting up a wiki. I think the wiki will have users cooperate directly into herds, herds can expose all types of information there (like status and future goals) and it could be useful for feature requests, ideas, interaction between everyone and it's a simple method for doing all this stuff. -- Luis Medinas [EMAIL PROTECTED] http://dev.gentoo.org/~metalgod Gentoo Linux Developer: AMD64,Printing,Media-Optical,Sound -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
-BEGIN PGP SIGNED MESSAGE- Hash: SHA1 Lance Albertson wrote: Luis Medinas wrote: On Sun, 2006-01-08 at 12:54 -0600, Lance Albertson wrote: snip snip I had thought about creating some kind of a site like this, but not necessarily in a wiki form. I don't like the idea of letting users add random docs. There's too much room for error and how do you deal with accountability? There has to be a developer who either will take the time to maintain it or accept responsibility for any errors it may have. I like the idea of having an area for herds to keep track of their internal thing, but I fear it will just end up replacing what the GDP (and our www site) does. Its too easy for them to just start adding docs there instead of on www because its 'too hard' to deal with guidexml. If the issue here is guidexml, lets figure out the problem. We need to define what exactly is the problem before we decide on an implementation. Is the problem that there's no central place for herds to put updates/goals/etc? Is the problem that there's no easy way for users to submit new docs for people to use? Is the problem that guidexml hampers development time with regard to creating docs and you wish to have a better/easier way to create such docs? Simply saying 'we need a public wiki' is great an all, but I'd rather ask 'What problem(s) does the wiki solve' before we even get farther. There might be better ways to solving the problem other than putting up a wiki. I think the big problem with certain pieces of documentation is the fact that: A) They change too often for any sort of static webpage. If I'm writing portage docs GuideXML is probably not how I want to go, the docs are essentially fluid for most of the development time, they change often, entire sections are ripped out and moved as I go. In that type of case any sort of static webpage is utterly horrible. Rather go a wiki route ( or something similar ) to allow easy access modification. One could say, build the docs offline and then submit them later for GDP to stick into GuideXML, but then only I can contribute to them ( myself not being a developer ). I guess I could host my own Anon-svn for the docs while they are being written, but not particularly my cup of tea. B) Non-developers want to contribute. The devwiki currently doesn't allow this, so I ended up asking Patrick at ge.org for an account to start a wiki there, hoping eventually to move it somewhere else ( or if events stay as they are, it can stay there ) Not many people want to make diffs on guideXML ( I know I hate editing it ), and to fix a small error or add a tidbit, no one wants to file a bug about it. Those are the two biggest, docs change fast and non-devs want to contribute to documentation in an easier way. Problems with any sort of wiki solution thats Gentoo-wide comes down to people editing projects they know nothing about, and managing permissions should they be implemented. I could probably do well editing the Portage section, but perhaps no so much in any Hardened area of the wiki. Problem is maintaining that number of users/permissions is a nightmare. But those are the two biggest problems in my estimation. No one wishes to impede the GDP here, Most of the docs I want to write are internal portage API docs/FAQ/Howto's, and I doubt you will see users pounding on the door to read them :) Alec Warner (antarus) -BEGIN PGP SIGNATURE- Version: GnuPG v1.4.2 (GNU/Linux) Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org iQIVAwUBQ8GBPWzglR5RwbyYAQINoA//U6CGfhwWcIKWOdr2UmbtarIbPoiFZ7Hc 2TcITLjnEqNFq28Va7cjKsS3Ef4BdoWY4UbhP+YCWPhqCPiFEOG4hEjsxeBQC4/v 7mvaC9EB2kVJRRZtl5WCtWeOzrsxc/ebtgOL1F8TL040AevD5BTYQKngS/9sEdl6 HyfY/i6Jbg5m8oFRCzA2vvzZAVHDPV92qxzKpfdfcAPC6FMHtdzimlASmcjjhAy2 FcUkYazzyy4888eO8tYZqpPX7ps8wUYVKfeLe55+EHpCC2jBp82NE++V2g9B0KcY 9T4yfELm1UXs1C4GDaukpqjrhj+vUSrf1/fK9k1ebmEaW29cEGATjYqCxKEXqQ8R iCTgvpWDkc9yFRBLjscVW5ZS+jjfST/YlyCuLFNbFKoze1fyj6xqVVwMbnONNklO X3979tn8bz377ZRNdbURkllc3Rgs0U6hHhowM917s2KULis4XnNhQ01DIomTH3cO a0BVZo0tCYcNxPLqqlMD2xqTpgRrN7NPOOSTJIWQyWrzctnF2RaeznJSd96zzVPB XDY/OsmRLulJIrAQcGQHpkYnhlk0Oy1kglWqXlvF8+Zf8O65qoFeSYvy2Ettuh06 jziyI4rDzfdDSgBmDX9jcShLoKIfoIxIGH6HvuphSXTIVqgDEr/63tEcYbXnomMv qNdS/bUOXAg= =rMLi -END PGP SIGNATURE- -- gentoo-dev@gentoo.org mailing list
Re: [gentoo-dev] Projects and simple guides
On Sun, 2006-01-08 at 12:54 -0600, Lance Albertson wrote: We could start a public wiki displaying all herds and projects. It would be great to add some low level docs, herds/project goals, ideas and so. Even the users could be allowed to edit and share information. Anything like that will need to be approved by the GDP and a GLEP. Are you sure? The new metastructure makes it perfectly clear that competing projects are okay. The GDP does not have a monopoly on documentation, only on what gets published through the /doc URLs on www.g.o. Best regards, Stu -- Stuart Herbert [EMAIL PROTECTED] Gentoo Developer http://www.gentoo.org/ http://blog.stuartherbert.com/ GnuGP key id# F9AFC57C available from http://pgp.mit.edu Key fingerprint = 31FB 50D4 1F88 E227 F319 C549 0C2F 80BA F9AF C57C -- signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] Projects and simple guides
On Sun, 8 Jan 2006 18:59:40 +0100 Diego 'Flameeyes' Pettenò [EMAIL PROTECTED] wrote: I originally thought of putting it on my devspace, but using GuideXML there is a bit tricky, at least for me (as xsltproc seems to refuse working on the pure xml directly). So I was thinking if we had a way to put some how to fix guides somewhere, on the lines of the ones written by soalr and vapier for hardened. A part the --as-needed thing, it might also be useful to put something about how to solve parallel make issues and similar things that are tricky but usually just requires little knowledge of tricks. GDP might be the place where to put them, but as they are mainly developer-oriented, they might be better accessed directly by devs (at least for the first steps until they are drafts). What people think about this? Find a nice place in www.gentoo.org/proj/ Marius -- Public Key at http://www.genone.de/info/gpg-key.pub In the beginning, there was nothing. And God said, 'Let there be Light.' And there was still nothing, but you could see a bit better. signature.asc Description: PGP signature
Re: [gentoo-dev] Projects and simple guides
On Sun, Jan 08, 2006 at 11:30:16PM +, Stuart Herbert wrote: On Sun, 2006-01-08 at 12:54 -0600, Lance Albertson wrote: We could start a public wiki displaying all herds and projects. It would be great to add some low level docs, herds/project goals, ideas and so. Even the users could be allowed to edit and share information. Anything like that will need to be approved by the GDP and a GLEP. Are you sure? The new metastructure makes it perfectly clear that competing projects are okay. The GDP does not have a monopoly on documentation, only on what gets published through the /doc URLs on www.g.o. Would like to see GDP reiterate this view actually, since I've a distinct memory last time I asked in irc about it I got an opposite answer from them. Regardless, (imo) it's already been laid out why guideXML'ifying everything doesn't totally work. Three reasons... A) bit of work required just to jot down a quick list of this is broke, fix it that's going to be thrown out 2 weeks down the line. B) guideXML requires actual vcs/shell access to commit the changes. Portage group relies fairly heavily on non-dev help to keep things going (throw cookies at antarus and zmedico, since they're the ones I speak of). Yes (generally speaking) non-devs will be minted at some point as devs if they've put in the effort, but there _is_ a sizable delay built in, thus no vcs/shell till after we've deemed they're going to be around for the long haul. C) delay in material commits to vcs actually hitting the web. Kind of hard discussing in irc what needs to be done and having the list that's being built up delayed due to cvs up reasons- yes this seems minor, but it results in people writing up crap text/html pages temporarily for the need, then dumping it into docs. Extra effort, I'd rather just modify the list in situ. Basically... docs route maintains the artificial barrier between devs and non devs, which bluntly, is stupid. If someone is contributing work, they're contributing work, as long as it doesn't suck I'm going to use their work regardless of whatever we've deemed them gentoo wise. Yes, for portage docs we have to lock sizable chunks of it down, but that is locking it down to the groupping of portage devs- both gentoo dev and non-gentoo dev. Note also I'm speaking mainly from a developmental angle- I'm not necessarily advocating that _non_ developmental docs be wikified, although there are pros to doing that. ~harring pgpK9wa6fwjNf.pgp Description: PGP signature
