[LLVMdev] Slight troubles following "Getting Started" instructions

[Joachim Durchholz]

Am Dienstag, den 26.02.2008, 16:32 -0800 schrieb Tanya M. Lattner:
> The document is called "Getting Started Guide", so I don't think it can 
> get more clear. It should probably be moved higher up in the docs list.

Actually finding the docs wasn't difficult. The challenge was following
the docs, deciding what's relevant and what isn't, deciding what to
install and what to leave out. Being unsure, one usually ends up trying
to install everything. That's good if you want to get a heads-up for all
the remaining warts of the software, but bad for attracting the unwashed
masses ;-)


How about adding a "who needs this" paragraph at the start of every
section of the Getting Started Guide? That way, everybody could easily
skip those parts that are irrelevant to him.

In the hope that it will help you laying out a plan for documentation
improvements, I prepared a list of groups that I see may be looking for
answers in the getting started guide:
1) People who use llvm as a tool. Subgroups are:
1a) Junior compiler writers wanting to install llvm and compile
something (in fact, anything), just to get a baseline in case things go
wrong later.
1b) Alpha testers for a compiler. The first step of their installation
instructions read "get and install llvm".
1c) Compiler writers who finally get around to writing something more
foolproof than "get and install llvm" for their beta testers. They will
probably copy the relevant parts of llvm installation instructions,
tailored towards the specific needs of their compilers.
1d) Distribution package maintainers who need to convert the
installation instructions into an automated installation script.
2) Compiler writers joining a project that uses llvm as a backend (these
will usually just get the "get and install llvm" line).
3) People who want to join the llvm project and hack on llvm.

Groups 1a-1d probably want the install instructions for the same package
sets, possibly with minor variations for each group.
Groups 1, 2, and 3 will probably want to install different parts of the
system.
Oh, and group 1d is probably too small to warrant any extra work for the
docs. Answering their questions in the mailing list might be less work
than keeping their special instructions up-to-date in the docs.

HTH.

> Exploring the guts of compilation and hooking up to the llvm backend are 
> more difficult topics. Documentation could be improved.

There's always room for incremental improvement.

Don't worry, I don't see the docs as bad (in fact I've seen much worse).
The docs just aren't polished to perfection yet :-)
(And I'm happy to see that there's interest in perfecting them!)

Regards,
Jo