On Wed, Jun 13, 2012 at 3:41 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:> Guys, that was very interesting and useful stuff you preached there. Mind > if I make a patch to the FAQ and include it somewhere? > > "Q: When should I develop against a branch? A: Only if you are making > really big or controversial changes. ... blah blah > > I am thinking that it would be highly useful for the project, if somebody > (yours sincerely) took it upon himself to hunt and gather the very > interesting bits that often pop up in these mailing lists. As a newbie, I > think the lists are very valuable, but you cannot expect people to always > read all of the old stuff on the lists and as much as we all love Google's > search engine (bing! bing!), it does always find the stuff you want to find > (nearly, but not always). >Yes, patches to the FAQ are very welcome. We should honestly organize the FAQ a bit differently if you want to start really working to flesh it out with more useful information. I think there should be three FAQs at least: 1) A FAQ for the LLVM Project, which is applicable to LLVM, Clang, and often other subprojects. This would include the license section in the current LLVM faq, and maybe some other points. 2) A FAQ for the LLVM codebase -- specific to the code, libraries, and infrastructure in the primary project. 3) A Clang FAQ for the FE-specific stuff. The current FAQ is mostly #2, with a bit of #1, and a lot of out-of-date or flat out wrong information. The current FAQ could probably stay as one page, or be two pages, but it should have a clear and well deliniated split between #1 and #2. We should discuss creating #3 on cfe-dev in a separate thread if you're interested. If you're proposing patches, here are some suggestions as the standard process may not work as well... which others may contradict if they disagree... ;] - Patches to fix the formatting / structure should go directly to llvm-commits - Patches to add a FAQ entry to section #1 above should at least go to llvm-commits, llvmdev, and possibly a few of the mailing lists for suprojects to get wider feedback. - Patches to add a FAQ entry to section #2 above should go to llvm-commits and llvmdev. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120613/ec5a721b/attachment.html>
I think the best way that I can currently contribute to the project is through technical writing. So I see myself as doing a serious, long-term project of extending the FAQ. So, I can affirm that I want to really start working :) This at the same time as I plan to regularly release an unofficial Windows distro of Clang with headers and libraries so people don't need to install MinGW to use Clang. I was myself thinking of a number of FAQs: 1. A General FAQ with high level questions like "What is the license?", "What is LLVM?", and "What is Clang?" Something that lifts the newcomer up to a fairly knowledgable state in a short time. 2. An LLVM User FAQ that only deals with LLVM usage questions. 3. An LLVM Dev FAQ that only deals with LLVM development questions. 4. A Clang User FAQ that only deals with Clang usage questions. 5. A Clang Dev FAQ that only deals with Clang development questions. 6. A you-name-it User FAQ that (lld comes to mind)... 7. A you-name-it Dev FAQ that... 8. A Technical Writer FAQ (should include the Sphinx documentation from the lld docs). I know this probably seems overwhelming at first, but LLVM + Clang are two gigantic projects that really need thousands of questions and answers, not only 10-15. Obviously, this won't materialize overnight, but I was thinking along that path. I have plenty of time and my commitment to the project is 100 percent as I badly need it for my own compiler project. I cannot stand coding on my compiler 24/7, so I figure I can use the breaks (days and weeks) to work on LLVM/Clang documentation. That way I won't have to swim in deep water (code), but can stay safely near the beach for the time being. Once I know enough about the project, I can perhaps jump in and begin coding myself. But meanwhile, I can spend my energy on making the transition from noob to guru that much easier for others who want to join it. I even see myself skimming through old posts on the mailing lists to gather useful stuff. And, perhaps, we can over time work out a system where you guys voluntarily cc: me whenever you give a strategic or important explanation you'd like to see included in the FAQ. There are many, many things that I think could benefit from being documented in a FAQ manner. For instance, how do you make an object file from a program that uses LLVM as its backend? (You don't need to answer, it is only an example, even though I am very curious about finding out about this sometime). Basically, I want to document what I learn while I transition from LLVM noob to advanced LLVM user (I doubt I'll make it to guru level, but advanced user is also fine for me). I'm printing your commit guidelines right after I send this reply. They are highly useful and even the mailing lists ought to have some FAQ entries - probably in the General FAQ. 2012/6/14 Chandler Carruth <chandlerc at google.com>> On Wed, Jun 13, 2012 at 3:41 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote: > >> Guys, that was very interesting and useful stuff you preached there. >> Mind if I make a patch to the FAQ and include it somewhere? >> >> "Q: When should I develop against a branch? A: Only if you are making >> really big or controversial changes. ... blah blah >> >> I am thinking that it would be highly useful for the project, if somebody >> (yours sincerely) took it upon himself to hunt and gather the very >> interesting bits that often pop up in these mailing lists. As a newbie, I >> think the lists are very valuable, but you cannot expect people to always >> read all of the old stuff on the lists and as much as we all love Google's >> search engine (bing! bing!), it does always find the stuff you want to find >> (nearly, but not always). >> > > Yes, patches to the FAQ are very welcome. > > We should honestly organize the FAQ a bit differently if you want to start > really working to flesh it out with more useful information. I think there > should be three FAQs at least: > > 1) A FAQ for the LLVM Project, which is applicable to LLVM, Clang, and > often other subprojects. This would include the license section in the > current LLVM faq, and maybe some other points. > > 2) A FAQ for the LLVM codebase -- specific to the code, libraries, and > infrastructure in the primary project. > > 3) A Clang FAQ for the FE-specific stuff. > > > The current FAQ is mostly #2, with a bit of #1, and a lot of out-of-date > or flat out wrong information. The current FAQ could probably stay as one > page, or be two pages, but it should have a clear and well deliniated split > between #1 and #2. We should discuss creating #3 on cfe-dev in a separate > thread if you're interested. > > > If you're proposing patches, here are some suggestions as the standard > process may not work as well... which others may contradict if they > disagree... ;] > > - Patches to fix the formatting / structure should go directly to > llvm-commits > > - Patches to add a FAQ entry to section #1 above should at least go to > llvm-commits, llvmdev, and possibly a few of the mailing lists for > suprojects to get wider feedback. > > - Patches to add a FAQ entry to section #2 above should go to llvm-commits > and llvmdev. >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/e8580ae5/attachment.html>
On Wed, Jun 13, 2012 at 4:37 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:> I think the best way that I can currently contribute to the project is > through technical writing. So I see myself as doing a serious, long-term > project of extending the FAQ. So, I can affirm that I want to really start > working :)Awesome. I was myself thinking of a number of FAQs:> > 1. A General FAQ with high level questions like "What is the license?", > "What is LLVM?", and "What is Clang?" Something that lifts the newcomer up > to a fairly knowledgable state in a short time. >SGTM.> 2. An LLVM User FAQ that only deals with LLVM usage questions. > 3. An LLVM Dev FAQ that only deals with LLVM development questions. > 4. A Clang User FAQ that only deals with Clang usage questions. > 5. A Clang Dev FAQ that only deals with Clang development questions. > 6. A you-name-it User FAQ that (lld comes to mind)... > 7. A you-name-it Dev FAQ that... > 8. A Technical Writer FAQ (should include the Sphinx documentation from > the lld docs). >All of these we usually deal with as manuals rather than FAQs, and I think that's a better strategy overall. We should ensure we have thorough and complete manuals, and only add FAQs to cover completely off-the-wall information that doesn't really have a good home, or a quick 10 questions that are almost always asked. Also, I think there should be only one manual for LLVM -- the line between 'user' and 'developer' is too blurry to be sensible in documentation. The organization of the documentation itself will naturally group things appropriately so that only the relevant sections need be read. Finally, I would focus on "user facing" FAQs for the quick 10 questions. I don't think developers will really be helped by these as often. -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120613/01a71a05/attachment.html>
> 8. A Technical Writer FAQ (should include the Sphinx documentation fromthe lld docs). I'm working on the Sphinx stuff; if you have any questions about writing Sphinx docs feel free to ask. --Sean Silva On Wed, Jun 13, 2012 at 4:37 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:> I think the best way that I can currently contribute to the project is > through technical writing. So I see myself as doing a serious, long-term > project of extending the FAQ. So, I can affirm that I want to really start > working :) This at the same time as I plan to regularly release an > unofficial Windows distro of Clang with headers and libraries so people > don't need to install MinGW to use Clang. > > I was myself thinking of a number of FAQs: > > 1. A General FAQ with high level questions like "What is the license?", > "What is LLVM?", and "What is Clang?" Something that lifts the newcomer up > to a fairly knowledgable state in a short time. > 2. An LLVM User FAQ that only deals with LLVM usage questions. > 3. An LLVM Dev FAQ that only deals with LLVM development questions. > 4. A Clang User FAQ that only deals with Clang usage questions. > 5. A Clang Dev FAQ that only deals with Clang development questions. > 6. A you-name-it User FAQ that (lld comes to mind)... > 7. A you-name-it Dev FAQ that... > 8. A Technical Writer FAQ (should include the Sphinx documentation from > the lld docs). > > I know this probably seems overwhelming at first, but LLVM + Clang are two > gigantic projects that really need thousands of questions and answers, not > only 10-15. Obviously, this won't materialize overnight, but I was > thinking along that path. I have plenty of time and my commitment to the > project is 100 percent as I badly need it for my own compiler project. I > cannot stand coding on my compiler 24/7, so I figure I can use the breaks > (days and weeks) to work on LLVM/Clang documentation. That way I won't > have to swim in deep water (code), but can stay safely near the beach for > the time being. Once I know enough about the project, I can perhaps jump > in and begin coding myself. But meanwhile, I can spend my energy on making > the transition from noob to guru that much easier for others who want to > join it. I even see myself skimming through old posts on the mailing lists > to gather useful stuff. And, perhaps, we can over time work out a system > where you guys voluntarily cc: me whenever you give a strategic or > important explanation you'd like to see included in the FAQ. > > There are many, many things that I think could benefit from being > documented in a FAQ manner. For instance, how do you make an object file > from a program that uses LLVM as its backend? (You don't need to answer, > it is only an example, even though I am very curious about finding out > about this sometime). Basically, I want to document what I learn while I > transition from LLVM noob to advanced LLVM user (I doubt I'll make it to > guru level, but advanced user is also fine for me). > > I'm printing your commit guidelines right after I send this reply. They > are highly useful and even the mailing lists ought to have some FAQ entries > - probably in the General FAQ. > > > 2012/6/14 Chandler Carruth <chandlerc at google.com> > >> On Wed, Jun 13, 2012 at 3:41 PM, Mikael Lyngvig <mikael at lyngvig.org>wrote: >> >>> Guys, that was very interesting and useful stuff you preached there. >>> Mind if I make a patch to the FAQ and include it somewhere? >>> >>> "Q: When should I develop against a branch? A: Only if you are making >>> really big or controversial changes. ... blah blah >>> >>> I am thinking that it would be highly useful for the project, if >>> somebody (yours sincerely) took it upon himself to hunt and gather the very >>> interesting bits that often pop up in these mailing lists. As a newbie, I >>> think the lists are very valuable, but you cannot expect people to always >>> read all of the old stuff on the lists and as much as we all love Google's >>> search engine (bing! bing!), it does always find the stuff you want to find >>> (nearly, but not always). >>> >> >> Yes, patches to the FAQ are very welcome. >> >> We should honestly organize the FAQ a bit differently if you want to >> start really working to flesh it out with more useful information. I think >> there should be three FAQs at least: >> >> 1) A FAQ for the LLVM Project, which is applicable to LLVM, Clang, and >> often other subprojects. This would include the license section in the >> current LLVM faq, and maybe some other points. >> >> 2) A FAQ for the LLVM codebase -- specific to the code, libraries, and >> infrastructure in the primary project. >> >> 3) A Clang FAQ for the FE-specific stuff. >> >> >> The current FAQ is mostly #2, with a bit of #1, and a lot of out-of-date >> or flat out wrong information. The current FAQ could probably stay as one >> page, or be two pages, but it should have a clear and well deliniated split >> between #1 and #2. We should discuss creating #3 on cfe-dev in a separate >> thread if you're interested. >> >> >> If you're proposing patches, here are some suggestions as the standard >> process may not work as well... which others may contradict if they >> disagree... ;] >> >> - Patches to fix the formatting / structure should go directly to >> llvm-commits >> >> - Patches to add a FAQ entry to section #1 above should at least go to >> llvm-commits, llvmdev, and possibly a few of the mailing lists for >> suprojects to get wider feedback. >> >> - Patches to add a FAQ entry to section #2 above should go to >> llvm-commits and llvmdev. >> > > > _______________________________________________ > LLVM Developers mailing list > LLVMdev at cs.uiuc.edu http://llvm.cs.uiuc.edu > http://lists.cs.uiuc.edu/mailman/listinfo/llvmdev > >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120613/bd4c32a0/attachment.html>