[LLVMdev] Develop on trunk.

[Andrew Trick]

Mikael, thanks for working on this. I can help review patches to some extent, but we'll need to recruit other reviewers.

I agree with Chandler's points, especially that this is a broad documentation problem, not really an FAQ problem.

I would like to see documentation clearly organized for three audiences, clang users, clang developers, and llvm developers. The early contents of this thread are related to "Developer Policies", although we're talking about guidelines/advice more than policies. This should be shared between clang and llvm developers.

I think the documentation should be minimal in the sense that it should only contain what isn't easy to decipher from source-generated documentation and should cross reference source-generated docs when needed.

I would only support formally documenting the advice in this thread because it affects the decisions that are made very early during project development and are politically hard to change later.

-Andy

On Jun 13, 2012, at 4:58 PM, Mikael Lyngvig <mikael at lyngvig.org> wrote:

> Okay with the manual versus FAQ strategy.  I just have to mention that languages like C++ has many FAQs all over the net, altogether totalling perhaps thousands of questions and I see C++ as simple compared to LLVM.
> 
> But I have plenty to do now.  If nothing else, I could try reading the manuals ;-)
> 
> 2012/6/14 Chandler Carruth <chandlerc at google.com>
> 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.
> 
> 
> 
> -- 
> -- Love Thy Frog!

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20120614/68292b91/attachment.html>