[LLVMdev] Documentation Issues Welcome?

[Bill Wendling]

On Feb 27, 2009, at 10:24 PM, William Moss wrote:

> 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. ;-)

> 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! :-)

> 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).