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 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190822/6eed290b/attachment.html>
Michael Kruse via llvm-dev
2019-Aug-22 20:13 UTC
[llvm-dev] Docs: Re-organizing the LLVM docs
I agree that llvm.org/docs is too long for a landing page. Especially some subcategories take too much space when someone is not looking for that subcategory. Thanks for your work! Michael Am Do., 22. Aug. 2019 um 13:14 Uhr schrieb via llvm-dev <llvm-dev at lists.llvm.org>:> > 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
David Blaikie via llvm-dev
2019-Aug-22 20:28 UTC
[llvm-dev] Docs: Re-organizing the LLVM docs
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>
Cranmer, Joshua via llvm-dev
2019-Aug-22 21:05 UTC
[llvm-dev] Docs: Re-organizing the LLVM docs
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<http://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 -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190822/7b65ba7c/attachment.html>
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 >-------------- next part -------------- An HTML attachment was scrubbed... URL: <http://lists.llvm.org/pipermail/llvm-dev/attachments/20190827/1659526b/attachment.html>