Re: links in confluence wiki (was Re: Documentation -- making better use of the wiki)
On 11/15/05, Jörg Schaible [EMAIL PROTECTED] wrote: Anuerin Diaz wrote on Monday, November 14, 2005 5:22 PM: hi, i am having problems trying to make a URL in the confluence wiki. the guidelines on the right side it should look like [title#anchor] but [why do i...#FAQ/why-do-i] does not work. I am trying to make the FAQ page as the itemized table of contents and organize the FAQ wikis using a directory/entry structure. [snip] It's pipe not a slash! '/' vs. '|' pipes replace the hashmarks but thanks for the heads up. what i meant for the slash is that it would point to a 'why-do-i' wiki that is under the FAQ wiki. it is so that if somebody lists down all wikis in the database then all FAQ wikis will be listed close to each other instead of being scattered all around the place. :D ciao! -- Programming, an artform that fights back Anuerin G. Diaz Registered Linux User #246176 Friendly Linux Board @ http://mandrivausers.org/index.php http://capsule.ramfree17.org , when you absolutely have nothing else better to do - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
RE: links in confluence wiki (was Re: Documentation -- making better use of the wiki)
Anuerin Diaz wrote on Monday, November 14, 2005 5:22 PM: hi, i am having problems trying to make a URL in the confluence wiki. the guidelines on the right side it should look like [title#anchor] but [why do i...#FAQ/why-do-i] does not work. I am trying to make the FAQ page as the itemized table of contents and organize the FAQ wikis using a directory/entry structure. [snip] It's pipe not a slash! '/' vs. '|' - Jörg - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
Jason, Can you add maven dev guys to this page? Thanks, Stéphane On 11/12/05, Emmanuel Venisse [EMAIL PROTECTED] wrote: Jason, I can't view it, I obtain You do not have permission to view this page. Emmanuel Jason van Zyl a écrit : On Sat, 2005-11-12 at 12:17 +0100, Alexander Hars wrote: Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. How so? You simply have to sign up? For example, unregistered users can't see its content, Fixed. Now anyone can see the content. That was a mistake in me setting it up. so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. That doesn't mean they can't start writing the doco. They don't have to wait for access to begin writing. But point taken. I will assume that the space will not be abused. The permissions are now wide open and anyone can add/edit/view content. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. Should be fixed with the permissions change. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. Possibly but a link checker would work better. Technical problems with the site we should be able to catch. The main site is not going to be opened wide for anonymous editing, we just can't do that. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. For this type of editing of existing work we can't let anonymous users edit the content. It's just not something we can do right now. The documentation that goes into the main site has to go through some vetting and process. That doesn't mean we can't try to do something to make this easier like create a plugin that automatically creates a patch and creates an issue and attaches the patch. I have been here for 5 years and it is nice to think that lots of users will contribute but that is generally not the case. It is 5-10 dedicated users who contribute much of the secondary documentation. That is certainly the case here. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. Then I guess we're not doing something right! :-) It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. Fair enough. I think we understand these things. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Absolutely but it has to be balanced with the process that we have for creating the documentation. We use APT and Confluence for everything and there simply won't be wide open access to the main body of documentation. But 1) The Maven User space can be wide open for any sort of contribution and if in Confluence format we have a chance of processing it along with the rest of doco we have in Confluence. 2) If a
Re: Documentation -- making better use of the wiki
On Sun, 2005-11-13 at 15:47 +0100, Stephane Nicoll wrote: Jason, Can you add maven dev guys to this page? It's simply wide open now. You should be able to edit at will. Thanks, Stéphane On 11/12/05, Emmanuel Venisse [EMAIL PROTECTED] wrote: Jason, I can't view it, I obtain You do not have permission to view this page. Emmanuel Jason van Zyl a écrit : On Sat, 2005-11-12 at 12:17 +0100, Alexander Hars wrote: Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. How so? You simply have to sign up? For example, unregistered users can't see its content, Fixed. Now anyone can see the content. That was a mistake in me setting it up. so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. That doesn't mean they can't start writing the doco. They don't have to wait for access to begin writing. But point taken. I will assume that the space will not be abused. The permissions are now wide open and anyone can add/edit/view content. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. Should be fixed with the permissions change. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. Possibly but a link checker would work better. Technical problems with the site we should be able to catch. The main site is not going to be opened wide for anonymous editing, we just can't do that. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. For this type of editing of existing work we can't let anonymous users edit the content. It's just not something we can do right now. The documentation that goes into the main site has to go through some vetting and process. That doesn't mean we can't try to do something to make this easier like create a plugin that automatically creates a patch and creates an issue and attaches the patch. I have been here for 5 years and it is nice to think that lots of users will contribute but that is generally not the case. It is 5-10 dedicated users who contribute much of the secondary documentation. That is certainly the case here. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. Then I guess we're not doing something right! :-) It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. Fair enough. I think we understand these things. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Absolutely but it has to be balanced with the process that we have for creating the documentation. We use APT and Confluence for everything and there simply won't be wide open
Re: Documentation -- making better use of the wiki
Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. For example, unregistered users can't see its content, so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Would you see a big problem if we started a trial with the Wiki? There is not much that we can loose. If nobody contributes or it really gets defaced all the time, we just stop. We don't loose anything. On the other hand, maybe we really get some users involved who submit snippets of insights and we reduce the learning curve. Would you really object if we wanted to launch a trial balloon for linking Maven documentation with the wiki? - Alexander - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
Although I'm not part of the original discussion, big +100 from me :) On 11/12/05, Alexander Hars [EMAIL PROTECTED] wrote: Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. For example, unregistered users can't see its content, so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Would you see a big problem if we started a trial with the Wiki? There is not much that we can loose. If nobody contributes or it really gets defaced all the time, we just stop. We don't loose anything. On the other hand, maybe we really get some users involved who submit snippets of insights and we reduce the learning curve. Would you really object if we wanted to launch a trial balloon for linking Maven documentation with the wiki? - Alexander - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
Provided that somehow this will (slowly, based on available time of maven devs) propagate back to the official Maven docs On 11/12/05, Arik Kfir [EMAIL PROTECTED] wrote: Although I'm not part of the original discussion, big +100 from me :) On 11/12/05, Alexander Hars [EMAIL PROTECTED] wrote: Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. For example, unregistered users can't see its content, so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Would you see a big problem if we started a trial with the Wiki? There is not much that we can loose. If nobody contributes or it really gets defaced all the time, we just stop. We don't loose anything. On the other hand, maybe we really get some users involved who submit snippets of insights and we reduce the learning curve. Would you really object if we wanted to launch a trial balloon for linking Maven documentation with the wiki? - Alexander - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
Jason, I can't view it, I obtain You do not have permission to view this page. Emmanuel Jason van Zyl a écrit : On Sat, 2005-11-12 at 12:17 +0100, Alexander Hars wrote: Jason, Thank you for setting up the mavenusers space on confluence. While this solution is certainly better for integrating the documentation with Maven, it has the disadvantage that it significantly raises the bar for anyone who wants to contribute. How so? You simply have to sign up? For example, unregistered users can't see its content, Fixed. Now anyone can see the content. That was a mistake in me setting it up. so they will not be drawn to improve on the documentation in the confluence wiki. In addition, anyone wishing to make a small contribution, will need to register, then send you an email, wait for the confirmation -- which will come quickly, I know, but will not be immediate. Most users will not bother. That doesn't mean they can't start writing the doco. They don't have to wait for access to begin writing. But point taken. I will assume that the space will not be abused. The permissions are now wide open and anyone can add/edit/view content. Let me give a few examples of possible user contributions that would not make it into a registered-users-only wiki: 1. Someone asked in the mailing lists about which archetypes are available by default with maven. Brett answered that by providing a useful link to ibiblio. I thought that this would be useful information for me, followed the link and made a mental note to check back the mailing list when I need this info sometimes in the future. When we started the discussion on the wiki, I just went to the wiki, added three or four lines for the archetypes I had found when following the link. Now I know, where to find it. Should be fixed with the permissions change. 2. I was looking through the guide to creating sites. There is a link to a description (A full reference of the APT Format is available). The link is dead. Of course I looked around a little more and found the full guide to the apt format. Of course I didn't bother sending this information to the mailing list. It looks like nit-picking but a wiki page would be ideal to put this information. Possibly but a link checker would work better. Technical problems with the site we should be able to catch. The main site is not going to be opened wide for anonymous editing, we just can't do that. 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. For this type of editing of existing work we can't let anonymous users edit the content. It's just not something we can do right now. The documentation that goes into the main site has to go through some vetting and process. That doesn't mean we can't try to do something to make this easier like create a plugin that automatically creates a patch and creates an issue and attaches the patch. I have been here for 5 years and it is nice to think that lots of users will contribute but that is generally not the case. It is 5-10 dedicated users who contribute much of the secondary documentation. That is certainly the case here. I know that you have worked hard at the documentation for Maven. But Maven is huge and complex. Then I guess we're not doing something right! :-) It is very difficult to put everything that users need into writing. And it is probably difficult for any experienced maven user - let alone developer - to understand how hard it is to learn Maven. Fair enough. I think we understand these things. In the past few weeks I have more than once regretted starting with Maven. It is a great tool, but whatever I start with, I find that it is so difficult to answer the basic questions that arise for the newbie. And I know that I am not the only one. It should not be like that (please don't take this as a criticism of the developers, I just think that there must be better ways to involve all of us in augmenting the documentation). Absolutely but it has to be balanced with the process that we have for creating the documentation. We use APT and Confluence for everything and there simply won't be wide open access to the main body of documentation. But 1) The Maven User space can be wide open for any sort of contribution and if in Confluence format we have a chance of processing it along with the rest of doco we have in Confluence. 2) If a particular user submits enough doco we consider giving them commit access to the documentation. Would you see a big problem if we started a trial with the Wiki? There is not much that we can loose. I'm all for it but use
Re: Documentation -- making better use of the wiki
On 11/12/05, Alexander Hars [EMAIL PROTECTED] wrote: 3. Yesterday Wendy Smoak noted in the mailing list that the guide for creating archetypes states that the id tag for the archetype.xml should be the same as the artifactId but that this is not the case for one of the plugins he used so the statement must be incorrect. It is very unlikely that an observation like this will be caught if we don't let the user who observes it contribute it easily. She is perfectly capable of submitting a patch, she just hasn't gotten around to it yet. ;) (There's also the problem on the 'Getting Started' page where after you do 'mvn archetype:create ...' it doesn't tell you to change into the newly created directory before typing 'mvn compile'.) -- Wendy - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
+1 Kind regards, Dave Sag Alexander Hars [EMAIL PROTECTED] wrote on 11-11-2005 10:42:58: Hi, I have been using Maven2 for two weeks and am very impressed by all the great features. However, the learning curve is steep and it is often very difficult to find certain answers (I often need to to look at the source code to find them). Whenever I find an answer to a question, I alone have learned. Others don't profit. I would be quite willing to submit an answer to Maven2 for inclusion into the guides. But that takes quite a bit of time (...going into CVS, downloading the apt file, modifying it, testing it, submitting it to someone for posting to the CVS etc.). I did that once, but we can't expect big progress in the documentation to occur this way. The only solution that does not overload the developers (who put in so much time already anyhow), is to make better use of the wiki because everybody can contribute and increase our cumulated knowledge. But just providing the wiki as it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There is almost nothing there, almost nobody goes to it, therefore few people add anything either. There are two practical ways in which we could make better use of the wiki: a) provide a prominent link from the Maven2 documentation (guides, miniguides, references, etc.) to a related wiki page. Anyone who has some insight to add to the documentation can place it there; anyone who has not found the answer in the standard documentation can easily check whether there is more information in the wiki. From time to time someone can integrate the bulk of good insights from the wiki back into the documentation. b) put most of the documentation into the wiki. In my opinion this is the ideal case, because it would reduce the load on the developers for providing the documentation and there would be a single documentation mechanism. But it is probably not practical because the Maven Wiki is not based on the .apt format and integration with the maven site generation mechanism may be difficult. Option a) is very easy to do. We would only need to create associated wiki pages and insert a link to the wiki page from the original documentation. I am sure that we could greatly expand the Maven-related knowledge this way. I certainly would be willing to work on the necessary changes to get this rolling if you think this is a good idea. - Alexander Hars - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
+1 Cheers, -Ralph. On 11.11.2005, at 11:01, David Sag wrote: +1 Kind regards, Dave Sag Alexander Hars [EMAIL PROTECTED] wrote on 11-11-2005 10:42:58: Hi, I have been using Maven2 for two weeks and am very impressed by all the great features. However, the learning curve is steep and it is often very difficult to find certain answers (I often need to to look at the source code to find them). Whenever I find an answer to a question, I alone have learned. Others don't profit. I would be quite willing to submit an answer to Maven2 for inclusion into the guides. But that takes quite a bit of time (...going into CVS, downloading the apt file, modifying it, testing it, submitting it to someone for posting to the CVS etc.). I did that once, but we can't expect big progress in the documentation to occur this way. The only solution that does not overload the developers (who put in so much time already anyhow), is to make better use of the wiki because everybody can contribute and increase our cumulated knowledge. But just providing the wiki as it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There is almost nothing there, almost nobody goes to it, therefore few people add anything either. There are two practical ways in which we could make better use of the wiki: a) provide a prominent link from the Maven2 documentation (guides, miniguides, references, etc.) to a related wiki page. Anyone who has some insight to add to the documentation can place it there; anyone who has not found the answer in the standard documentation can easily check whether there is more information in the wiki. From time to time someone can integrate the bulk of good insights from the wiki back into the documentation. b) put most of the documentation into the wiki. In my opinion this is the ideal case, because it would reduce the load on the developers for providing the documentation and there would be a single documentation mechanism. But it is probably not practical because the Maven Wiki is not based on the .apt format and integration with the maven site generation mechanism may be difficult. Option a) is very easy to do. We would only need to create associated wiki pages and insert a link to the wiki page from the original documentation. I am sure that we could greatly expand the Maven-related knowledge this way. I certainly would be willing to work on the necessary changes to get this rolling if you think this is a good idea. - Alexander Hars - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
this idea has been going around. the maven developers rely on JIRA for the prioritization of their task so if you really want this proposal to be accepted then you can vote on this task http://jira.codehaus.org/browse/MNG-1521 it is a placemarker JIRA task containing Alexander's suggestion below. ciao! On 11/11/05, Alexander Hars [EMAIL PROTECTED] wrote: Hi, I have been using Maven2 for two weeks and am very impressed by all the great features. However, the learning curve is steep and it is often very difficult to find certain answers (I often need to to look at the source code to find them). Whenever I find an answer to a question, I alone have learned. Others don't profit. I would be quite willing to submit an answer to Maven2 for inclusion into the guides. But that takes quite a bit of time (...going into CVS, downloading the apt file, modifying it, testing it, submitting it to someone for posting to the CVS etc.). I did that once, but we can't expect big progress in the documentation to occur this way. The only solution that does not overload the developers (who put in so much time already anyhow), is to make better use of the wiki because everybody can contribute and increase our cumulated knowledge. But just providing the wiki as it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There is almost nothing there, almost nobody goes to it, therefore few people add anything either. There are two practical ways in which we could make better use of the wiki: a) provide a prominent link from the Maven2 documentation (guides, miniguides, references, etc.) to a related wiki page. Anyone who has some insight to add to the documentation can place it there; anyone who has not found the answer in the standard documentation can easily check whether there is more information in the wiki. From time to time someone can integrate the bulk of good insights from the wiki back into the documentation. b) put most of the documentation into the wiki. In my opinion this is the ideal case, because it would reduce the load on the developers for providing the documentation and there would be a single documentation mechanism. But it is probably not practical because the Maven Wiki is not based on the .apt format and integration with the maven site generation mechanism may be difficult. Option a) is very easy to do. We would only need to create associated wiki pages and insert a link to the wiki page from the original documentation. I am sure that we could greatly expand the Maven-related knowledge this way. I certainly would be willing to work on the necessary changes to get this rolling if you think this is a good idea. - Alexander Hars - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED] -- Programming, an artform that fights back Anuerin G. Diaz Registered Linux User #246176 Friendly Linux Board @ http://mandrivausers.org/index.php http://capsule.ramfree17.org , when you absolutely have nothing else better to do - To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
Re: Documentation -- making better use of the wiki
On Fri, 2005-11-11 at 10:42 +0100, Alexander Hars wrote: Hi, I have been using Maven2 for two weeks and am very impressed by all the great features. However, the learning curve is steep and it is often very difficult to find certain answers (I often need to to look at the source code to find them). Whenever I find an answer to a question, I alone have learned. Others don't profit. I would be quite willing to submit an answer to Maven2 for inclusion into the guides. But that takes quite a bit of time (...going into CVS, downloading the apt file, modifying it, testing it, submitting it to someone for posting to the CVS etc.). That what actually saves us time. Being able to easily integrate it into what we have now. I'm not saying this ideal, but using a wiki isn't going to magically make this process better. I did that once, but we can't expect big progress in the documentation to occur this way. In your case, the patch went in very quickly and was published but we didn't redirect the old m2 site to its new location and you didn't see it but it was processed pretty quickly. So, as the person who has done most of the doco for m2 I can say that I love patches. The only solution that does not overload the developers (who put in so much time already anyhow), is to make better use of the wiki because everybody can contribute and increase our cumulated knowledge. But just providing the wiki as it is now (http://wiki.apache.org/maven/Maven2Info) does not work. There is almost nothing there, almost nobody goes to it, therefore few people add anything either. I encourage users to place content in the wiki and it will get processed when we have time but patches are better if you want the material to make it into the main site. There are two practical ways in which we could make better use of the wiki: a) provide a prominent link from the Maven2 documentation (guides, miniguides, references, etc.) to a related wiki page. Anyone who has some insight to add to the documentation can place it there; anyone who has not found the answer in the standard documentation can easily check whether there is more information in the wiki. From time to time someone can integrate the bulk of good insights from the wiki back into the documentation. Unfortunately we have had problems with the Apache wiki being defaced so we stopped using it. b) put most of the documentation into the wiki. In my opinion this is the ideal case, because it would reduce the load on the developers for providing the documentation and there would be a single documentation mechanism. It does not reduce the load on developers because having everything in the wiki does not make for good documentation. I'm not saying what we have is stellar but again the wiki is not a panacea. Ideally what we would like is an APT-based wiki with staging/editing capabilities but until that happens having to make a patch is a pretty good vetting process for content. But it is probably not practical because the Maven Wiki is not based on the .apt format and integration with the maven site generation mechanism may be difficult. Exactly. Now I haven't looked at the Apache Wiki in a while but what is possible is to create a doxia parser for moin moin and then we could more easily integrate it. If someone did that I would probably look at the wiki, but otherwise it just creates more work having to convert it. We are working on some tools to pull content out of Confluence and integrate it with the site so what we may also be able to do is setup a space for Maven users to work on content and then we can automatically pull stuff out of Confluence. We use Confluence and I would prefer not start using another wiki until we get an APT-based wiki. We would probably also need people to ask for access because leaving the wiki wide open has caused problems in the past. Option a) is very easy to do. We would only need to create associated wiki pages and insert a link to the wiki page from the original documentation. I am sure that we could greatly expand the Maven-related knowledge this way. I truly admire your enthusiasm and I will work with you if you want to try and come up with a solution but in my experience the total ad hoc solution doesn't work. I certainly would be willing to work on the necessary changes to get this rolling if you think this is a good idea. Helping to work on the confluence tools would probably be the best place to start, but in the mean time for people who want to start creating content I can create a space on Confluence and anyone who wants access just needs to ask and I will set you up asap if you want to write content. You can actually sign up yourself and then I can turn on your access and you can write all you like! I will set something up now. - Alexander Hars - To unsubscribe,
