On Nov 11, 2010, at 5:08 AM, Renato Golin wrote:> On 11 November 2010 07:46, Chris Lattner <clattner at apple.com>
wrote:
>> It's actually not any harder to change and keep up to date than
anything else. HTML pages have the advantage of showing up in a recursive grep
of the sourcebase, and showing up in llvm-commits so they fall into the peer
review process.
>
> Hi Chris,
>
> I understand that this is more of a personal preference than a
> technical discussion...
>
> Diff-ing HTML is not easy and enforcing style even less. Most Wiki
> have revision control (albeit, different than your main svn repo),
> good diffing and collaboration tools.
>
> It's true that both HTML and Wiki tend to become out-dated if no one
> maintains it and a blog post is outdated by definition, but explicitly
> done so (dated).
>
> I agree that blog posts are good to convey decisions made, but would
> be good to have it immortalized somewhere (HTML or Wiki).
It's true that this is partially about personal preference, but it goes
beyond that. The wiki doesn't fit into the social infrastructure we have
for the project: changes to it aren't reviewed on a -commits list, people
without commit access can modify it, etc. Depending on your perspective, this
is a good thing or bad thing. One datapoint is that UIUC refuses to host
wiki.llvm.org specifically because they have policies against hosting web sites
with no control over the content.
Beyond the social aspects, the wiki doesn't fit into our release
infrastructure either. llvm/docs is snapshotted with each release and archived.
This helps with changing APIs and other stuff, which means that you can read
about LLVM 1.0's alias analysis stuff at
http://llvm.org/releases/1.0/docs/AliasAnalysis.html if you really want to :)
Because the wiki is not in SVN, it can't realistically do this.
>> If you're liking the Wiki because you don't have commit access
to the LLVM repo (making it harder to update the docs there) then we should
grant you commit access.
>
> That's not the point. The story goes like this...
>
> Me, Devang and Talin were discussing the document I've written about
> debug information. Both sent me lots of corrections, typos,
> suggestions, in the body of the email, which I had to change the HTML
> doc and re-send them. Every iteration they would find things, suggest
> others, until Talin said: we should put this in the Wiki!
>
> While this is pretty much what you said (draft writing on wiki), there
> are lots of things that will remain draft quality for a long time,
> like how to produce debug information.
As I mentioned, I don't have a problem with using the wiki as a
collaborative development tool, so long as useful docs migrate back to the
official html docs.
> So, as you said, people should write drafts in Wiki and more finalized
> documents in HTML (a I concur), Wikis are good to start documents, and
> HTML are good to immortalize them. So, encouraging people to start
> docs in the wiki and having a way to convert them to HTML (I found
> some Python scripts in Google code) would be a good thing.
>
> Later additions, when the HTML doc is already stable, could be
> manageable via SVN diff.
Right. My next objection is that the wiki isn't being used just for
collaborative development. For example, the "common backend tasks",
"faq", "using llvm" and other stuff should be merged into
the official docs. I'm fine keeping wishlist and external project lists on
the wiki.
-Chris