[dtrace-discuss] Re: Conventions for documenting USDT probes?

[Nik Clayton]

Michelle Olson wrote:
> Some other ideas on this topic...The sources for the Solaris Dynamic
> Tracing Guide are available on the download center in DocBook XML via the
> Docs Consolidation. So, you can edit those files and send them as a patch
> and we'll have a Sun sponsor copy them into the answerbook. Or we could
> set up a Project for future changes to the book, so we can just keep the
> files in a repository. Let me know what you think, if there is some way I
> can help.
> 
> http://dlc.sun.com/osol/docs/downloads/

I've found DocBook to be the way to go for any sort of official 
documentation.  I've got a lot of experience managing the FreeBSD 
documentation set in this way.

I'd suggest not having a competing wiki, since it just splits the effort.

What would be great would be an annotation mechanism for the documents, so 
that it's easy for people to contribute fixes or updates quickly, without 
having to go through the rigamarole of learning DocBook, installing a 
processing environment, and so on.  I'm thinking of something a little like

    http://www.annocpan.org/

but for DocBook.  I've no idea if such a thing exists or not...

As and when my Ultra 40 arrives (http://jc.ngo.org.uk/blog/) I'll be making 
a point of contributing to the DTrace docs.

N