dtrace discuss - Nov 2007 - Solaris Dynamic Tracing Guide gets Wikified!

Tracers,

Good news! The Solaris Dynamic Tracing Guide has entered
the participation age at last and has been converted into
wiki format. The new and shiny guide can be found at:

http://wikis.sun.com/display/DTrace/Documentation

The guide has fallen behind with developments in DTrace
since it was first released and needs some revising and
some bug fixing as well. However, now that it''s in an
easily editable format, you can be a real star in the
DTrace community by putting your literary skills to
good work...

We welcome anyone who would like to contribute to the
community by working on updating and improving the guide.
Adam has put up a list of doc bugs that are currently
logged and you can find them at:

http://wikis.sun.com/display/DTrace/Documentation+Bugs

Feel free to start editing the docs. If you plan to make
changes that are larger than a typo please first send email
to dtrace-discuss at opensolaris.org and wait for approval
from a core contributor or for 5 days to pass.

To gain access to the DTrace wiki space contact Adam
(adam.leventhal at sun.com). If you are working on a bug
from the bug list make sure you update the owner column of
the bug to reflect the fact. When you''ve finished please
update the column in the bug list to reflect that fact.

That''s it! This procedure is subject to change but we''ll
see how it goes. One of us will notify the list if it changes.

Finally, over 400 pages were converted from SGML->wiki in
this process so one or two very minor errors may have crept
in during the conversion process. If you notice any, please feel
free to either fix them yourself or notify me directly.


Thanks.

Jon.

On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam
wrote:
> To gain access to the DTrace wiki space contact Adam
> (adam.leventhal at sun.com). If you are working on a bug
> from the bug list make sure you update the owner column of
> the bug to reflect the fact. When you''ve finished please
> update the column in the bug list to reflect that fact.
Actually, there''s no need to contact me or anyone: the wiki is open for
all
registered users to modify. We''ll tighted up security if we have any
problems.
> Finally, over 400 pages were converted from SGML->wiki in
> this process so one or two very minor errors may have crept
> in during the conversion process. If you notice any, please feel
> free to either fix them yourself or notify me directly.
A big thanks to Jon for undertaking this. If you''ve been looking for a
way
to contribute to the community, improving the documentation is a great
way to do so.

Adam

-- 
Adam Leventhal, FishWorks                        http://blogs.sun.com/ahl

At 10:23 -0800 28/11/07, Adam Leventhal wrote:
>On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam wrote:
>>  To gain access to the DTrace wiki space contact Adam
>>  (adam.leventhal at sun.com). If you are working on a bug
>>  from the bug list make sure you update the owner column of
>>  the bug to reflect the fact. When you''ve finished please
>>  update the column in the bug list to reflect that fact.
>
>Actually, there''s no need to contact me or anyone: the wiki is open
for all
>registered users to modify. We''ll tighted up security if we have
any problems.
How do you want to handle platform-specific changes?  As I stumble 
across Mac OS X specific stuff, I''d like to add it to the book.  To 
me that makes a lot more sense that maintaining a separate "DTrace on 
Mac OS X" document.

For example, the discussion of the "stop" action says that you can 
start a process using "prun", but that''s not available on Mac
OS X.
On Mac OS X you can use "kill -CONT <pid>".  I''d love
to just go in
there and add a note to that effect, but I figured I''d ask about 
formatting conventions first.

S+E
-- 
Quinn "The Eskimo!"                   
<http://www.apple.com/developer/>
Apple Developer Relations, Developer Technical Support, Core OS/Hardware

Great question. As a dtrace user and documentation reader, I would not 
want to
need to flip to another chapter, or another section, to read about 
platform differences
for a particular provider, function, etc. I''m not saying you suggested 
that, I''m just
thinking out loud...

I think a reasonable way to do this, and maintain consistency, is to add 
a "Platform Notes"
heading to each section - or perhaps at a Chapter granularity.

Within Platform Notes, we have subsections for "Mac OS X",
"FreeBSD", etc,
and add the platform specific notes there.

It may also be useful to add a chapter that discusses platform 
differences at a
high level.

Just some thoughts...if the platform differences are not vast enough to 
warrant
adding format changes to the document, perhaps they can be handled in 
footnotes.
(keeping in mind footnotes are considered poor writing style).

Thanks,
/jim


Quinn wrote:
> At 10:23 -0800 28/11/07, Adam Leventhal wrote:
>   
>> On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam wrote:
>>     
>>>  To gain access to the DTrace wiki space contact Adam
>>>  (adam.leventhal at sun.com). If you are working on a bug
>>>  from the bug list make sure you update the owner column of
>>>  the bug to reflect the fact. When you''ve finished please
>>>  update the column in the bug list to reflect that fact.
>>>       
>> Actually, there''s no need to contact me or anyone: the wiki is
open for all
>> registered users to modify. We''ll tighted up security if we
have any problems.
>>     
>
> How do you want to handle platform-specific changes?  As I stumble 
> across Mac OS X specific stuff, I''d like to add it to the book. 
To
> me that makes a lot more sense that maintaining a separate "DTrace on 
> Mac OS X" document.
>
> For example, the discussion of the "stop" action says that you
can
> start a process using "prun", but that''s not available
on Mac OS X.
> On Mac OS X you can use "kill -CONT <pid>".  I''d
love to just go in
> there and add a note to that effect, but I figured I''d ask about 
> formatting conventions first.
>
> S+E
>

Since this thread''s been resurrected I''ll toss in this
question:

Will it be possible to print an up-to-date DTrace Guide from the wiki 
content?   The latest manual in pdf (that I can find) is from 2005.  
Occasionally it''s handy to have a printed guide as a reference, but the
wiki doesn''t lend itself well to printed format...  or does it?

Kevin



Jon Haslam wrote:
> Tracers,
>
> Good news! The Solaris Dynamic Tracing Guide has entered
> the participation age at last and has been converted into
> wiki format. The new and shiny guide can be found at:
>
> http://wikis.sun.com/display/DTrace/Documentation
>
> The guide has fallen behind with developments in DTrace
> since it was first released and needs some revising and
> some bug fixing as well. However, now that it''s in an
> easily editable format, you can be a real star in the
> DTrace community by putting your literary skills to
> good work...
>
> We welcome anyone who would like to contribute to the
> community by working on updating and improving the guide.
> Adam has put up a list of doc bugs that are currently
> logged and you can find them at:
>
> http://wikis.sun.com/display/DTrace/Documentation+Bugs
>
> Feel free to start editing the docs. If you plan to make
> changes that are larger than a typo please first send email
> to dtrace-discuss at opensolaris.org and wait for approval
> from a core contributor or for 5 days to pass.
>
> To gain access to the DTrace wiki space contact Adam
> (adam.leventhal at sun.com). If you are working on a bug
> from the bug list make sure you update the owner column of
> the bug to reflect the fact. When you''ve finished please
> update the column in the bug list to reflect that fact.
>
> That''s it! This procedure is subject to change but we''ll
> see how it goes. One of us will notify the list if it changes.
>
> Finally, over 400 pages were converted from SGML->wiki in
> this process so one or two very minor errors may have crept
> in during the conversion process. If you notice any, please feel
> free to either fix them yourself or notify me directly.
>
>
> Thanks.
>
> Jon.
> _______________________________________________
> dtrace-discuss mailing list
> dtrace-discuss at opensolaris.org
>

Agreed. We were thinking of doing exactly this. The provider chapters would
be a great place to start. There should be a table in each describing the
support on various platforms as well as any usage notes which might apply.

Adam

On Thu, Dec 13, 2007 at 10:37:01AM -0500, Jim Mauro
wrote:
> 
> Great question. As a dtrace user and documentation reader, I would not 
> want to
> need to flip to another chapter, or another section, to read about 
> platform differences
> for a particular provider, function, etc. I''m not saying you
suggested
> that, I''m just
> thinking out loud...
> 
> I think a reasonable way to do this, and maintain consistency, is to add 
> a "Platform Notes"
> heading to each section - or perhaps at a Chapter granularity.
> 
> Within Platform Notes, we have subsections for "Mac OS X",
"FreeBSD", etc,
> and add the platform specific notes there.
> 
> It may also be useful to add a chapter that discusses platform 
> differences at a
> high level.
> 
> Just some thoughts...if the platform differences are not vast enough to 
> warrant
> adding format changes to the document, perhaps they can be handled in 
> footnotes.
> (keeping in mind footnotes are considered poor writing style).
> 
> Thanks,
> /jim
> 
> 
> Quinn wrote:
> > At 10:23 -0800 28/11/07, Adam Leventhal wrote:
> >   
> >> On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam wrote:
> >>     
> >>>  To gain access to the DTrace wiki space contact Adam
> >>>  (adam.leventhal at sun.com). If you are working on a bug
> >>>  from the bug list make sure you update the owner column of
> >>>  the bug to reflect the fact. When you''ve finished
please
> >>>  update the column in the bug list to reflect that fact.
> >>>       
> >> Actually, there''s no need to contact me or anyone: the
wiki is open for all
> >> registered users to modify. We''ll tighted up security if
we have any problems.
> >>     
> >
> > How do you want to handle platform-specific changes?  As I stumble 
> > across Mac OS X specific stuff, I''d like to add it to the
book.  To
> > me that makes a lot more sense that maintaining a separate
"DTrace on
> > Mac OS X" document.
> >
> > For example, the discussion of the "stop" action says that
you can
> > start a process using "prun", but that''s not
available on Mac OS X.
> > On Mac OS X you can use "kill -CONT <pid>". 
I''d love to just go in
> > there and add a note to that effect, but I figured I''d ask
about
> > formatting conventions first.
> >
> > S+E
> >   
> _______________________________________________
> dtrace-discuss mailing list
> dtrace-discuss at opensolaris.org
-- 
Adam Leventhal, FishWorks                        http://blogs.sun.com/ahl

Hi All,
Now that the dtrace guide has been wikified, what happens with the guide 
on docs.sun.com?
Should I look at the wikified guide, or the (dated) guide on 
docs.sun.com?  I have the same question
about the Modular Debugger guide.  Also, any chance of changing the 
dashboard page to
include MDB with the "Solaris Modular Debugger" line?  I went to 
wikis.sun.com and searched the page
for mdb and didn''t find it.  Then I searched for debug and there it
was.

thanks,
max

Adam Leventhal wrote:
> Agreed. We were thinking of doing exactly this. The provider chapters would
> be a great place to start. There should be a table in each describing the
> support on various platforms as well as any usage notes which might apply.
>
> Adam
>
> On Thu, Dec 13, 2007 at 10:37:01AM -0500, Jim Mauro wrote:
>   
>> Great question. As a dtrace user and documentation reader, I would not 
>> want to
>> need to flip to another chapter, or another section, to read about 
>> platform differences
>> for a particular provider, function, etc. I''m not saying you
suggested
>> that, I''m just
>> thinking out loud...
>>
>> I think a reasonable way to do this, and maintain consistency, is to
add
>> a "Platform Notes"
>> heading to each section - or perhaps at a Chapter granularity.
>>
>> Within Platform Notes, we have subsections for "Mac OS X",
"FreeBSD", etc,
>> and add the platform specific notes there.
>>
>> It may also be useful to add a chapter that discusses platform 
>> differences at a
>> high level.
>>
>> Just some thoughts...if the platform differences are not vast enough to
>> warrant
>> adding format changes to the document, perhaps they can be handled in 
>> footnotes.
>> (keeping in mind footnotes are considered poor writing style).
>>
>> Thanks,
>> /jim
>>
>>
>> Quinn wrote:
>>     
>>> At 10:23 -0800 28/11/07, Adam Leventhal wrote:
>>>   
>>>       
>>>> On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam wrote:
>>>>     
>>>>         
>>>>>  To gain access to the DTrace wiki space contact Adam
>>>>>  (adam.leventhal at sun.com). If you are working on a bug
>>>>>  from the bug list make sure you update the owner column of
>>>>>  the bug to reflect the fact. When you''ve finished
please
>>>>>  update the column in the bug list to reflect that fact.
>>>>>       
>>>>>           
>>>> Actually, there''s no need to contact me or anyone: the
wiki is open for all
>>>> registered users to modify. We''ll tighted up security
if we have any problems.
>>>>     
>>>>         
>>> How do you want to handle platform-specific changes?  As I stumble 
>>> across Mac OS X specific stuff, I''d like to add it to the
book.  To
>>> me that makes a lot more sense that maintaining a separate
"DTrace on
>>> Mac OS X" document.
>>>
>>> For example, the discussion of the "stop" action says
that you can
>>> start a process using "prun", but that''s not
available on Mac OS X.
>>> On Mac OS X you can use "kill -CONT <pid>". 
I''d love to just go in
>>> there and add a note to that effect, but I figured I''d ask
about
>>> formatting conventions first.
>>>
>>> S+E
>>>   
>>>       
>> _______________________________________________
>> dtrace-discuss mailing list
>> dtrace-discuss at opensolaris.org
>>     
>
>

Hi Max,

Feel free to look at both! The wiki should offer slightly more up
to date content than the docs.sun.com version but the changes on the
wiki should trickle through to the docs.sun.com version.

The MDB guide on the wiki isn''t quite finished yet so you
really should stick to the docs.sun.com version until I find
the time to finish it.

Jon.
> Hi All,
> Now that the dtrace guide has been wikified, what happens with the guide 
> on docs.sun.com?
> Should I look at the wikified guide, or the (dated) guide on 
> docs.sun.com?  I have the same question
> about the Modular Debugger guide.  Also, any chance of changing the 
> dashboard page to
> include MDB with the "Solaris Modular Debugger" line?  I went to 
> wikis.sun.com and searched the page
> for mdb and didn''t find it.  Then I searched for debug and there
it was.
>
> thanks,
> max
>
> Adam Leventhal wrote:
>   
>> Agreed. We were thinking of doing exactly this. The provider chapters
would
>> be a great place to start. There should be a table in each describing
the
>> support on various platforms as well as any usage notes which might
apply.
>>
>> Adam
>>
>> On Thu, Dec 13, 2007 at 10:37:01AM -0500, Jim Mauro wrote:
>>   
>>     
>>> Great question. As a dtrace user and documentation reader, I would
not
>>> want to
>>> need to flip to another chapter, or another section, to read about 
>>> platform differences
>>> for a particular provider, function, etc. I''m not saying
you suggested
>>> that, I''m just
>>> thinking out loud...
>>>
>>> I think a reasonable way to do this, and maintain consistency, is
to add
>>> a "Platform Notes"
>>> heading to each section - or perhaps at a Chapter granularity.
>>>
>>> Within Platform Notes, we have subsections for "Mac OS
X", "FreeBSD", etc,
>>> and add the platform specific notes there.
>>>
>>> It may also be useful to add a chapter that discusses platform 
>>> differences at a
>>> high level.
>>>
>>> Just some thoughts...if the platform differences are not vast
enough to
>>> warrant
>>> adding format changes to the document, perhaps they can be handled
in
>>> footnotes.
>>> (keeping in mind footnotes are considered poor writing style).
>>>
>>> Thanks,
>>> /jim
>>>
>>>
>>> Quinn wrote:
>>>     
>>>       
>>>> At 10:23 -0800 28/11/07, Adam Leventhal wrote:
>>>>   
>>>>       
>>>>         
>>>>> On Tue, Nov 27, 2007 at 07:46:37PM +0000, Jon Haslam wrote:
>>>>>     
>>>>>         
>>>>>           
>>>>>>  To gain access to the DTrace wiki space contact Adam
>>>>>>  (adam.leventhal at sun.com). If you are working on a
bug
>>>>>>  from the bug list make sure you update the owner
column of
>>>>>>  the bug to reflect the fact. When you''ve
finished please
>>>>>>  update the column in the bug list to reflect that
fact.
>>>>>>       
>>>>>>           
>>>>>>             
>>>>> Actually, there''s no need to contact me or anyone:
the wiki is open for all
>>>>> registered users to modify. We''ll tighted up
security if we have any problems.
>>>>>     
>>>>>         
>>>>>           
>>>> How do you want to handle platform-specific changes?  As I
stumble
>>>> across Mac OS X specific stuff, I''d like to add it to
the book.  To
>>>> me that makes a lot more sense that maintaining a separate
"DTrace on
>>>> Mac OS X" document.
>>>>
>>>> For example, the discussion of the "stop" action says
that you can
>>>> start a process using "prun", but that''s not
available on Mac OS X.
>>>> On Mac OS X you can use "kill -CONT <pid>". 
I''d love to just go in
>>>> there and add a note to that effect, but I figured I''d
ask about
>>>> formatting conventions first.
>>>>
>>>> S+E
>>>>   
>>>>       
>>>>         
>>> _______________________________________________
>>> dtrace-discuss mailing list
>>> dtrace-discuss at opensolaris.org
>>>     
>>>       
>>   
>>     
>
> _______________________________________________
> dtrace-discuss mailing list
> dtrace-discuss at opensolaris.org
>