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

[via llvm-dev]

Sure, not a problem. I'll add this to my list of tasks.

-DeForest

On Tue, Aug 27, 2019, 2:39 PM Alex Brachet-Mialot <
alexbrachetmialot at gmail.com> wrote:

> Also, if you have time to get to it Bug 42505
> <https://bugs.llvm.org/show_bug.cgi?id=42505> highlights how many links
> are relative to https://llvm.org/docs/ which I don't think they should
> be. It means the docs can't be hosted anywhere other than llvm.org,
> including locally when you build the docs (the links will go to llvm.org,
> not the local copy as expected). Moreover a lot of links in CommandGuide go
> nowhere (and I suspect the docs in other directories too), stemming from
> this problem I believe.
>
> On Tue, Aug 27, 2019 at 3:09 PM via llvm-dev <llvm-dev at lists.llvm.org>
> wrote:
>
>> Thanks everyone for your suggestions. The doc development phase of the
>> Season of Docs program starts next week. I'll be posting my proposed
>> changes via this mailing list in the next day or so.
>>
>> On Thu, Aug 22, 2019 at 3:05 PM Cranmer, Joshua <joshua.cranmer at intel.com>
>> wrote:
>>
>>> The break-down of “User Guides”, “Programming Documentation”, and
>>> “Subsystem Documentation” has always been difficult for me to remember
>>> which group the document I’m looking for is actually in.
>>>
>>>
>>>
>>> I’d propose a breakdown that looks more like this:
>>>
>>> # How to build/package/dockerize/etc. LLVM (it’s surprising how many
>>> pages we have on this!)
>>>
>>> # How to use LLVM tools. This is the “I’m using LLVM solely from the
>>> command-line, what do I do?” section.
>>>
>>> # The LLVM Reference – this would include the Language Reference as well
>>> as backend-specific pages that describe how target-specific information
>>> works for those targets (honestly, we could use more of that), the details
>>> of atomics and exception handling, etc. This is the “I’m writing/reading
>>> LLVM IR, what do I do?” section.
>>>
>>> # The LLVM API Reference – this covers the links to Doxygen, description
>>> on the AliasAnalysis interface, etc. This is the “I’m using LLVM as a
>>> library (or to write a pass, or a backend, or within LLVM itself), what do
>>> I do?” section, and it probably warrants a few subsections (e.g., details
>>> for backend implementation).
>>>
>>>
>>>
>>> The rest of the documents are hard to categorize, being a mix of
>>> documentation of formats (say the .PDB documentation guide), description of
>>> LLVM passes, details of implementation approaches (e.g., Spectre
>>> mitigations), and some information for people who want to understand
>>> terminology.
>>>
>>>
>>>
>>> *From:* llvm-dev [mailto:llvm-dev-bounces at lists.llvm.org] *On Behalf Of
>>> *via llvm-dev
>>> *Sent:* Thursday, August 22, 2019 14:14
>>> *To:* llvm-dev <llvm-dev at lists.llvm.org>
>>> *Subject:* [llvm-dev] Docs: Re-organizing the LLVM docs
>>>
>>>
>>>
>>> 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/20190827/c0a12678/attachment.html>