<div dir="ltr"><div>Also, if you have time to get to it <a href="https://bugs.llvm.org/show_bug.cgi?id=42505" target="_blank">Bug 42505</a> highlights how many links are relative to <a href="https://llvm.org/docs/" target="_blank">https://llvm.org/docs/</a> which I don't think they should be. It means the docs can't be hosted anywhere other than <a href="http://llvm.org" target="_blank">llvm.org</a>, including locally when you build the docs (the links will go to <a href="http://llvm.org">llvm.org</a>, 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.<br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Tue, Aug 27, 2019 at 3:09 PM via llvm-dev <<a href="mailto:llvm-dev@lists.llvm.org">llvm-dev@lists.llvm.org</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">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.</div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Aug 22, 2019 at 3:05 PM Cranmer, Joshua <<a href="mailto:joshua.cranmer@intel.com" target="_blank">joshua.cranmer@intel.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<div lang="EN-US">
<div class="gmail-m_-5345197089440502514gmail-m_-7131721373570393778WordSection1">
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">I’d propose a breakdown that looks more like this:<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"># How to build/package/dockerize/etc. LLVM (it’s surprising how many pages we have on this!)<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"># How to use LLVM tools. This is the “I’m using LLVM solely from the command-line, what do I do?” section.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"># 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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"># 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).<u></u><u></u></span></p>
<p class="MsoNormal"><a name="m_-5345197089440502514_m_-7131721373570393778__MailEndCompose"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></a></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)">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.<u></u><u></u></span></p>
<p class="MsoNormal"><span style="font-size:11pt;font-family:Calibri,sans-serif;color:rgb(31,73,125)"><u></u> <u></u></span></p>
<div style="border-style:none none none solid;border-left:1.5pt solid blue;padding:0in 0in 0in 4pt">
<div>
<div style="border-style:solid none none;border-top:1pt solid rgb(225,225,225);padding:3pt 0in 0in">
<p class="MsoNormal"><a name="m_-5345197089440502514_m_-7131721373570393778______replyseparator"></a><b><span style="font-size:11pt;font-family:Calibri,sans-serif">From:</span></b><span style="font-size:11pt;font-family:Calibri,sans-serif"> llvm-dev [mailto:<a href="mailto:llvm-dev-bounces@lists.llvm.org" target="_blank">llvm-dev-bounces@lists.llvm.org</a>]
<b>On Behalf Of </b>via llvm-dev<br>
<b>Sent:</b> Thursday, August 22, 2019 14:14<br>
<b>To:</b> llvm-dev <<a href="mailto:llvm-dev@lists.llvm.org" target="_blank">llvm-dev@lists.llvm.org</a>><br>
<b>Subject:</b> [llvm-dev] Docs: Re-organizing the LLVM docs<u></u><u></u></span></p>
</div>
</div>
<p class="MsoNormal"><u></u> <u></u></p>
<div>
<div>
<p style="margin:0in 0in 0.0001pt"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">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 (</span><a href="http://llvm.org/docs" target="_blank"><span style="font-family:"Helvetica Neue",serif;color:rgb(228,175,10)">llvm.org/docs</span></a><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">)
into a landing page of sorts. Here’s an example of how the new index page might look:<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"># Welcome/About<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Introduction and overview of LLVM<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Topic links<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"># Getting Started/Tutorials<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Brief description w/topic links<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"># Reference<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Brief description w/topic links<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"># Getting Involved/Community<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Overview of how to get involved with the LLVM project<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">* Topic links<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">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.<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">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.<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal;min-height:14px"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">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.<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)"><u></u> <u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">Thanks,<u></u><u></u></span></p>
<p style="margin:0in 0in 0.0001pt;font-stretch:normal"><span style="font-family:"Helvetica Neue",serif;color:rgb(69,69,69)">DeForest<u></u><u></u></span></p>
</div>
</div>
</div>
</div>
</div>
</blockquote></div>
_______________________________________________<br>
LLVM Developers mailing list<br>
<a href="mailto:llvm-dev@lists.llvm.org" target="_blank">llvm-dev@lists.llvm.org</a><br>
<a href="https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev" rel="noreferrer" target="_blank">https://lists.llvm.org/cgi-bin/mailman/listinfo/llvm-dev</a><br>
</blockquote></div>