[llvm-commits] Refactor Sphinx homepage

[Daniel Dunbar]

On Thu, Jun 21, 2012 at 8:52 PM, Sean Silva <silvas at purdue.edu> wrote:
>> We currently conflate two different topics under the moniker of
>> "LLVM": the "LLVM project" (organization, developer policy, website,
>
> Agreed. This is a sticky rhetorical problem. I agree that structural
> division of the documentation is the best way to address this. The
> titles need to be as unambiguous as possible for this scheme to be
> maximally effective, so maybe "LLVM Umbrella Project" should be
> preferred to "LLVM Project" in the outline you gave.

Yup. In the longer term, I think we might want to move to referring to
LLVM-the-source-tree-and-set-of-libraries as "LLVM Core".

>
>> In my mind, this kind of table of contents follows a structure that is
>> much more related to the way to code / tasks are organized, which
>> makes it easier to know where new documentation needs to fit, and how
>> to slice up the existing documentation to fit it into a more useful
>> structure.
>>
>> What do you think of this general idea?
>
> I like it. It's definitely a huge step up from the current state of affairs.
>
> One thing that I think we need to especially plan on is tutorials.
> Tutorials are currently LLVM's biggest weak-spot documentationwise
> (other than the horrible organization). Tutorials for LLVM are
> woefully lacking, and the few existing ones are hard to find and
> bit-rot very quickly. Some of the stuff in the examples/ directory are
> awesome, only needing a little bit of human narrative to become
> excellent tutorials. The most lacking one is a walkthrough of
> examples/Fibonacci IMO.

Agreed.

Although, I will also say that tutorials are something core
contributors are less likely to write; I hope that one gain we see as
part of moving to Sphinx is that contributors are more likely to keep
the technical documentation up to date.

> As far as moving to this new documentation organization, I think that
> a good plan is to make a push to get everything into Sphinx. Once that
> is done, this organization can be imposed through the toctree with
> minimal churn. Once that is done, we will be able to see the outline
> of the documentation on one page, and it should be easy to identify
> and fill in any missing pieces.

Agreed. My main goal is that we have all the Sphinx conversion done
for 3.2 (including Clang and maybe LLDB). That would already be a big
step forward.

> There's a really good talk about documentation by one of the lead
> Django developers at
> <http://blip.tv/pycon-us-videos-2009-2010-2011/pycon-2011-writing-great-documentation-4899042>.
> Slides at <http://bit.ly/i8o8B4> (look at slide 24 and the immediately
> preceding slides). Another presentation that is good has slides at
> <http://www.oscon.com/oscon2010/public/schedule/detail/14000>.
>
> Both emphasize 4 main divisions of documentation and that these
> divisions are fractal in that they apply to different levels (whole
> project, single subsystem, single module, etc). Definitely worth
> checking out.

Nice, thanks for the links.

 - Daniel

> --Sean Silva
>
> On Thu, Jun 21, 2012 at 2:01 PM, Daniel Dunbar <daniel at zuster.org> wrote:
>>
>> Hi Sean,
>>
>> I'm a bit behind the times, so hopefully this reply isn't too out of
>> date, but I'm super happy to see you are interested in working on
>> this.
>>
>> I completely agree the current division is terrible, I also very much
>> wanted to refactor it but decided it was too big of a project to take
>> on at the same time as the conversion to .rst, so I figured I would
>> translate the old docs and then think about the right way to
>> restructure.
>>
>> One of the big problems with the current structure is that it although
>> it ostensibly tries to divide the documentation into logical sections
>> for different audiences ("users" vs "developers"), the division is
>> done very poorly. We also have a lot of little tiny bits of
>> information posing as "guides", but these aren't integrated into any
>> kind of cohesive whole.
>>
>> At the moment, one of the big problems with the current division is
>> that it is hard to do better than just read *all* the docs when you
>> want to find out stuff about LLVM, because it isn't clear where you
>> should be looking for information.
>>
>> I generally agree with your plan (I think) of merging the various top
>> level documents, with one exception.
>>
>> We currently conflate two different topics under the moniker of
>> "LLVM": the "LLVM project" (organization, developer policy, website,
>> mailing lists, etc.), and the "LLVM core" (the LLVM library which is a
>> part of the LLVM project). Chris and I discussed this problem
>> recently, and I think it would behoove us to try and keep these two
>> topics separate  (and keep the documentation for them separate).
>>
>> The next direction I would propose for the technical content (the bulk
>> of what is there) is to try and organize the leaf documents into
>> something resembling more of a "manual". The division of documents
>> between "design & overview", "user guides", "api clients", and
>> "subsystems" is really arbitrary and not at all helpful. I believe
>> this started as an idea to separate documentation to appeal to
>> different audiences, but the division between the various groups is
>> too arbitrary.
>>
>> Instead, I would propose that we organize the documentation more along
>> the lines of the division and structure that exists in the project,
>> and clearly communicate the TOC, and then let users find the documents
>> they need.
>>
>> With that in mind, here is a rough 10 minute outline of how I would
>> organize the "LLVM manual", focused at natural divisions of the
>> project itself (not of its audience):
>>
>> Introduction
>> LLVM Project
>>  Overview
>>  Development Policy (DeveloperPolicy)
>>  Coding Standards (CodingStandards)
>>  Release Process (HowToReleaseLLVM)
>>  Project Guide (Projects)
>>  Mailing Lists (mailing_lists)
>> LLVM Core
>>  Getting Started (Getting Started)
>>  Architectural Overview
>>    (cover the interaction between IR, mid-level stuff, backend stuff,
>> and other pieces like the JIT)
>>  Support libraries
>>    Data structures
>>    System library
>>  The Intermediate Representation
>>    LangRef
>>    The C++ API to the IR
>>    llvm-as, llvm-dis, llvm-extract, etc.
>>    The bit code format
>>    ... other stuff (like GEP faq) ...
>>  Mid-Level Optimization
>>    Overview
>>    Pass Manager
>>    Alias Analysis
>>    The 'opt' tool
>>    ...
>>  Backend Infrastructure
>>     Target independent code generator
>>     tablegen
>>     The 'llc' tool
>>     Writing a new backend
>>     ...
>>
>> In my mind, this kind of table of contents follows a structure that is
>> much more related to the way to code / tasks are organized, which
>> makes it easier to know where new documentation needs to fit, and how
>> to slice up the existing documentation to fit it into a more useful
>> structure.
>>
>> What do you think of this general idea?
>>
>>  - Daniel
>>
>> On Sat, Jun 9, 2012 at 12:49 AM, Sean Silva <silvas at purdue.edu> wrote:
>> > This is a first step towards structuring the Sphinx docs better to make
>> > them
>> > easier to browse and use. It doesn't change the structure or contents of
>> > the
>> > docs at all.
>> >
>> > In a future patch, I'm planning on taking each of
>> >
>> >    design_and_overview.rst
>> >    userguides.rst
>> >    programming.rst
>> >    subsystems.rst
>> >    development_process.rst
>> >    mailing_lists.rst
>> >
>> > and reintegrating them into the homepage. This will be similar to how
>> > the
>> > old html docs homepage was, so it will be familiar (and super-fast to
>> > search
>> > with Ctrl-f, which I've seen at least one other person miss). The
>> > current
>> > setup is just really bulky and hard to navigate, being on different
>> > pages,
>> > when there's really not that much there, certainly not enough to merit
>> > splitting up.
>> >
>> > Another thing, but an important one, is that the way the current docs
>> > are
>> > laid out in the reST source makes the end result incredibly ugly. For
>> > example, the lists are indented by a space or two in the .rst file,
>> > which
>> > causes Sphinx to emit a list of indented bullets, even though the
>> > bullets
>> > are logically at the top level. Also, semantically, they should be
>> > definition lists, not bulleted lists.
>> >
>> > I'll be fixing all of these things once I get my feet wet with this
>> > patch.
>> >
>> > Feedback on which direction to take the docs after that would be
>> > appreciated.
>> >
>> > --Sean Silva
>> >
>> > _______________________________________________
>> > llvm-commits mailing list
>> > llvm-commits at cs.uiuc.edu
>> > http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>> >