Documentation Issues Welcome?

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

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?

We always welcome feedback! Especially in areas where programmers are loathe to tread. :wink:

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?

Not at all! :slight_smile:

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?

If it's generated, then you'll have to find the generator and patch that...In this case, it was a .pod file in docs/CommandGuide. Fixed.

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.

The Stacker project was removed after 2.4, so those documents are probably out of date at the moment. They should be removed. (I don't know if Chris already has plans in place to do this for the March 2nd release.)

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.

The quote is glib and tries at humor. But if we don't provide the information the programmer needs, then that's a serious bug. We try to document features as best as we can. Cleaning up spelling, grammar, and formatting will help make the documentation more palatable.

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.

Thanks for the offer of help! Any patches or suggestions you send along will be most appreciated.

-bw

P.S. Just so you know, LLVM doesn't do minor releases. We have a release schedule of 3 months, so doing a minor release isn't all that profitable (if there's a bug, someone can just wait a few months for the next release).