[LLVMdev] Develop on trunk.

Wed Jun 13 20:10:00 PDT 2012

I just finished up the first draft of the FAQ translated verbatim from HTML
to Sphinx.  Sphinx did puzzle me a few times but I got used to its
approximate error messages and figured out what the problems were.

Perhaps you could take a quick glance at this file and tell me if I am
doing something wrong?  Otherwise I'll send it off to llvm-commits and see
what they say.

Thanks,
Mikael

2012/6/14 Sean Silva <silvas at purdue.edu>

> > 8. A Technical Writer FAQ (should include the Sphinx documentation from
> the 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
>>
>>
>

-- 
-- Love Thy Frog!
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/c5934a31/attachment.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: FAQ.rst
Type: application/octet-stream
Size: 18571 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/c5934a31/attachment.obj>