[LLVMdev] Documentation Issues Welcome?

[William Moss]

Having recently become interested in llvm I've read a lot of
documentation on your website. Considering that a 2.5
release is due out soon, I'm guessing there will be
additional readers and writers focusing on the docs. 
Would feedback in this area be welcome?

Simple misspellings of words on various pages like
Subvresion, producess, performsn, instructiosn, catagory,
and mis-behaving seem kind of "naked" if they're the only
thing in a patch. Since it's also likely such simple errors
will be caught the next time someone makes a real content
update, is a patch overkill for minor issues such as this?

There are some errors which seem to be on pages of
"generated" documentation. Submitting a patches to the HTML
would be erased after the next regeneration. For example,
the page http://llvm.org/cmds/llvm-bcanalyzer.html has a
broken link at the bottom of page to
http://llvm.org/docs/BitcodeFormat.html which will fail due
to an uncapitalized C in the word BitCode. But this looks
like it has to be patched at a higher level than just the
raw html, or does it?

There are also things I might suggest which aren't wrong,
but which you might be better off by changing them.
For example, changing the section titles on llvm.org home
page to say "Release Milestones" and "Meeting Highlights"
instead of "Upcoming Releases" and "Upcoming Meeting" since
some (most?) of the content covered in those sections is
still relevant to readers despite being in the past. Such
editorial changes aren't a simple matter of grammar or
correctness though.

With some more complex things I don't have a clue what the
"correct" way is supposed to be to even know what would be
the appropriate area to patch. Something still seems wrong
about the way that it is currently documented. stkrc is a
good example. The page http://llvm.org/docs/ mentions stkrc
among the list of "current tools". This tool is listed among
the man pages on http://llvm.org/docs/CommandGuide/man/man1/
but it is not linked from more direct list of current tools
on http://llvm.org/docs/CommandGuide/ It appears to be more
of a demo than a tool itself, but its absence from the
CommandGuide page looks like it might be an oversight rather
than an intentional removal. When you actually get to the
http://llvm.org/cmds/stkrc.html page, references in the
Description and See Also portions point the reader to the
http://llvm.org/docs/Stacker.html page. This is an invalid
link among the current docs though. Google can quickly point
one to the page in an older release of the documentation
http://llvm.org/releases/1.1/docs/Stacker.html but this
raises the question of whether the omission is due to
irrelevance and old age or just the burden of having to keep
up multiple pages pointing to their proper places on a big
website like this.

On the issue of style again, I have to mention that
documentation shortcomings don't seem major until escalated
in the documentation itself like the repeated admonition in
the Getting Started Quickly section: "Read the
documentation. Read the documentation. Remember that you
were warned twice about reading the documentation." The
imperfections in the documentation become much more annoying
after that. Both the simple things like spelling and printer
unfriendly formatting. But also the annoying questions such
admonitions leave unanswered about the scope and source of
documentation we're being chided about repeatedly. (Is this
page sufficient reading material? Should we look at the
entire docs directory? How familiar should one be with the
tool chain for building files on their local filesystem? and
so on...) Again, I'd have no idea how to answer such
questions so I wouldn't know how to raise the issue other
than pointing out the sincere annoyance on the mailing list.

Documentation isn't ever a big day-to-day focus. The work
you have been doing on llvm, clang, and the automatic
bug finder code has been phenomenal and I'll gladly take
prosaic documentation if that means faster development. But
since 2.5 is a big "numeric" milestone whether folks have
followed the project or not, there will be more eyes
focusing on the docs so I thought I'd at least ask about
the issue.

--William