[LLVMdev] Develop on trunk.

[Sean Silva]

> 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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120613/bd4c32a0/attachment.html>