[llvm-dev] Docs: Re-organizing the LLVM docs

[David Blaikie via llvm-dev]

Hey - thanks for looking into/working on this!

I was going to suggest differentiating between user-facing tools and
compiler-developer tools, but that's a bit of a fuzzy line (someone who
cares a lot about their compiled code might end up looking at
optimizations, LLVM IR, etc) - though might still be a useful grouping.

Some stuff in Subsystem documentation, for instance, overlaps with some of
the "command guide" - like bugpoint. I think command guide would be
top-level "here's all the command utilities" maybe broken down/separated by
user-facing V not (or "shades of user facing").

(I guess that's the trick with this being LLVM documentation, rather than
Clang documentation - anyone who's actually thinking about "LLVM" is
already, maybe(?) a compiler person - not just a user of clang, etc)

Sorry, this has ended up more rambly and less useful than I hoped - perhaps
it gives some ideas/things to talk about?

On Thu, Aug 22, 2019 at 11:14 AM via llvm-dev <llvm-dev at lists.llvm.org>
wrote:

> As part of my Google Season of Docs project, I’ve been conducting a
> content audit of the LLVM docs. My goal is to identify specific categories
> and tasks under which the docs can be re-organized. One of my first
> suggestions will be to turn the main index (llvm.org/docs) into a landing
> page of sorts. Here’s an example of how the new index page might look:
>
>
> # Welcome/About
>
> * Introduction and overview of LLVM
>
> * Topic links
>
>
> # Getting Started/Tutorials
>
> * Brief description w/topic links
>
>
> # Reference
>
> * Brief description w/topic links
>
>
> # Getting Involved/Community
>
> * Overview of how to get involved with the LLVM project
>
> * Topic links
>
>
> Due to the sheer number of topics, there would also need to be
> “sub-pages”. For example, there could be a separate Reference page that
> lists all of the available reference topics by category.
>
>
> One thing I’m having trouble with is determining how to split up (i.e.,
> categorize) the many topics listed under User Guides, Programming
> Documentation, and Subsystem Documentation. Some topics are easier to
> categorize than others, such as topics specific to getting started,
> troubleshooting, logging bugs, etc. But other topics are harder to
> categorize. Should they be broken up based on where they fall within the
> LLVM toolchain? For example, a category for topics specific to the
> Optimizer.
>
>
> Given that you’re all more familiar with the LLVM project than I am, I’d
> be curious to get your thoughts/suggestions as to how you might split up
> the docs to make it easier for new and existing users to locate the
> information they need.
>
>
> Thanks,
>
> DeForest
> _______________________________________________
> LLVM Developers mailing list
> llvm-dev at lists.llvm.org
> https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190822/c1f01aaf/attachment.html>