[Bug documentation/6751] New: Web site mega-review

["jkenisto at us dot ibm dot com" <sourceware-bugzilla at sourceware dot org>]

As requested, I'm submitting this as a bug report.  We can divide it up into
multiple bugzillas if needed.

Yes, I could have made many of the wiki changes myself, but I decided (a) at
least some of the suggested changes should be reviewed, and (b) this (zero
unreviewed changes) is the easiset place to draw the line.
-----
General: Make /usr/local/share/doc/systemtap/examples available
on the web site ("Sample Scripts"?).  If we haven't already, make sure
useful examples from other parts of the web site (e.g., War Stories,
Demo) are captured there.

Home page:
----------
- Update mention of probing user-space apps.
- Add Oracle to list of members.

Get Involved page:
------------------
Under "Communicate", systemtap@sources.redhat.com should not be a link,
since what you need to do in order to subscribe is right there on the
"Get Involved" page, and the link just opens up a mailer window.

Seems like the "Try It Out" section should link to two new pages:
- Downloads: Instructions for installing SystemTap from one of the
releases (e.g., 0.7) or a weekly snapshot.  This should also clarify
that some distros provide particular versions of SystemTap.  Release
notes such as mjw's go here.
- Installing SystemTap: Links to installation/configuration
instructions for the various distros.  (See my comments on the wiki.)
This page should probably also give an overview of the components
you may need to install/configure in addition to SystemTap:
vmlinux/debuginfo, elfutils, ...

The home page should link to the Downloads page, which should
in turn link to the Installing SystemTap page.

"stap -c df ..." script takes a long time to respond, produces copious
output, uses several non-intuitive features.

Under "Contribute", s/critique, test/use, critique, test/

Documentation page:
-------------------

I reviewed the individual documents only lightly or not at all.

Demo:
The document at the "Description of the Programs" link has many and
conspicuous typos.  Also, it wasn't clear to me at first that it's
a script for a demo.  A couple of sentences up front to clarify this
would help.  Or change the link to "Demo Script" or some such.

Why do all these examples use ms (e.g., timer.ms(10000) instead of sec
(e.g., timer.sec(10))?

top.stp doesn't use the syscalls tapset, or the "limit 20" feature
of foreach.

prof.stp doesn't use the syscall tapset.  It needs a bit of an edit.
Seems like output should be sorted by syscall name, etc.

In kmalloc2.stp, change
	foreach ([name] in kmalloc)
to
	foreach (name in kmalloc)

At least some of the man pages (e.g., stap, stapfuncs) are out of date.

The "Systemtap Examples" man page is rather bare, considering all the
examples around.

We need a "System Call probe points" man page.  Just lift the
introductory comment from syscalls.stp and add that arg names match
the Red Hat man pages.

Links page:
-----------
Remove the "Dprobes and Kprobes Archives" section.

Wiki page:
----------
There seems to be some lack of clarity of what goes in the "For Users"
section and what goes in "For Developers".  E.g., just about any
stap user would need to visit one of the "SystemTap on ..." links,
but those are in the "For Developers" section.  Is "For Developers"
for the folks actually working on SystemTap, or for people developing
stap scripts and/or tapsets?

Consider creating a new wiki page, "Installing SystemTap", that links
to all the "SystemTap on ..." pages.  We'd want to keep the "Installing
SystemTap" page in the wiki so people can add to it, but we'd want to
link to it from the "Downloads" page.

Wiki - For Users section:

War Stories:
This is good stuff overall.  Maybe add a 1-line description to each link
on the War Stories page.

Tips:
Tag line is wrong: the FAQ isn't here.

DeveloperSetupTips:
- Right now this just has info on setting up a network console on Fedora.
Perhaps make the title more specific.  Also, this has nothing to do with
SystemTap per se.  At least clarify that.  Maybe move it down the list.
- FWIW, there's a link to this toward the bottom of the wiki page.

Cross-compiling probes:
- Shouldn't this employ the -m option?
- This page demonstrates a neat feature of staprun that I don't see
documented anywhere: the ability to specify an initial value for a
global (?) script variable on the staprun command line -- in this case,
	staprun xxx.ko k=mom
Note that
	stap xxx.stp k=mom
does NOT do this sort of substitution.

Small demos in Code Repository: This link is broken.

Wishlist:
This doesn't have much useful info.  Could this yield the results of
querying for unresolved enhancement requests in the bugzilla?

Scripts & Tools:
This should be near the top of the list.

Language Reference:
Do we still need this in the wiki, since it's now linked from the
Documentation page?

How to report bugs:
Fix the reference to CVS.

systemtap.py plugin for Son Of Sysreport (SOS):
Both the systemtap.py link and the Son of Sysreport link go to the
same page.  It's not clear why this is here.  Should it be linked
from the "How to report bugs" page?

Test Results:
This hasn't been updated since 12/14/07.

Using Markers:
- Is this up to date?  In particular, I'm wondering about "How do I
turn on marker support in my kernel?"
- In the first code sample, in the first call to trace_mark(),
s/inode, op/i, op/.

SystemTap FAQ:
Seems like this should be closer to the top.  It should also be
linked from the Documentation page.

Using a long URL as the label for a link (as is done several times
in the FAQ) is ugly.

Questions could be grouped more effectively -- e.g:
- #5 + #12
- #9 + #9.5 (new) + #6 + #10 + #18 (new)
- #1 + #17

#1: The links to the tutorial aren't very helpful.

#3:
- Given that Q2 is referenced in the question, it's not helpful to
suggest it in the answer.
- It's probably more typical to symlink to vmlinux from /boot than
to copy vmlinux to /boot.

#4:
- I'd think the important point is that you can get the C code
using "stap -p3".  -k is of secondary importance.
- The two "stap -p3" commands are smooshed together.

#5:
- The reader may infer that SystemTap ships with prebuilt modules.
Is this true of any distro?
- Given caching, using prebuilt modules isn't terribly important,
unless you want to allow stapusr users to run scripts; but that's
not touched on here.
- Ref #12 here.  Consider moving them closer together.
- A more likely question might be, "How can I run the same script
repeatedly without recompiling it?"
- It's important to note that a module can be prebuilt only
against the kernel version/build with which it will run.
- Seems like we should explain the "approved" way to prebuild
modules (stap -m).
- Using the URL as the label for the link isn't very helpful.

#6: s/some tapsets functions fails/tapset functions fail/

#7:
- Shouldn't the URLs be converted to links?
- Mention the script-examples page?

#8:
- s/in systemtap generated "C" module./in the systemtap-generated
C module?/
- Rather than the "man stap" code box, how about this?
For example, "stap -DMAXSTRINGLEN=256 xxx.stp" allows strings to
be up to 256 characters in the C code generated for xxx.stp.
See the stap(1) man page for a list of such macros.

#9:
- Seems like this ("What is a tapset?") should come before #6.
- The answer is kind of lame without the context provided by the
tutorial.  How about this?
A tapset is a special kind of systemtap script that defines
probepoints ("probe aliases") and auxiliary functions for use by
other scripts.  A probe alias defines a probepoint and supplies
selected values that are available when that probepoint is hit.
Think of a tapset as a library of probepoints and/or functions.
By default, systemtap looks for tapsets in the standard directory
(see #9.5), but you can specify your own tapset directories
using the stap -I option.

Add:
#9.5 Where is the standard tapset directory?
When built from source, it's /usr/local/share/systemtap/tapset.
For some distros, it's /usr/share/systemtap/tapset.

#10:
- s/systemtap community/The systemtap community/
- s/tapset dveloper guide/Tapset Developer's Guide/
- Change the link label to "Tapset Developer's Guide".
- The last sentence can probably be deleted, given #9.5.

#12: Suggested rewrite:
Yes.  Anybody can write and compile a script, but in order to run
it, you must be root or a member of group stapusr or group stapdev.
stapdev members can run any scripts.  stapusr members can run only
prebuilt modules (.ko files) that have been placed in
/lib/modules/`uname -r`/systemtap.

#13:
- Drop "This is fantastic!"  I doubt that we are Frequently Asked
Questions that begin with "This is fantastic!"  Especially when added
to the "way cool" comment on #7, it sounds phony.
- "Internals of translation in systemtap is described in src/INTERNALS*
file."  Better: "Internals of the systemtap translator are described
in the INTERNALS file in the source tree."
- s/at kernel source/in the kernel source/
- Put the link to the INTERNALS file in the above text.

#14: Change the link to the "Installing SystemTap" page, if we
create one.

#15:
- s/at systemtap bugzilla/at the systemtap bugzilla:/
- Make the bugzilla URL a link.
- s/Drop us a note/Or drop us a note/
- Since the "enter_bug" page at the indicated URL demands a password,
we should probably add something like:
To view the bug list, visit http://sourceware.org/bugzilla/query.cgi
[link], set Product=systemtap, and click Search.

#16:
- s/Where to I/Where do I/
- Replace the URLish link label with 'our "Get Involved" page'.
- Given the suggested addition to #15, the parenthetical comment
can be deleted.

#17:
- s/ues/use/
- Perhaps this should be replaced with a link to the proposed
"Installing SystemTap" page.

Add #18:
18) Where are descriptions of functions and probe aliases provided
by the standard tapsets?
Many functions are described in the Language Reference guide
[link] and the stapfuncs ("SystemTap Functions") man page [link
to the "Man Pages" section of the "Documentation" page].  Most
tapsets for kernel subsystems have associated "probe points"
man pages.

[end of FAQ comments]

Wiki - For Developers section:

No offense, but I don't think the Maemo/N800 entries should get
top billing in this section.

I didn't review the individual "SystemTap on..." pages.

See above about whether the "SystemTap on ..." links should be
on an "Installing SystemTap" page, or at least in a different
section of the wiki.

Should there be "SystemTap on RHEL x.x" pages?

SystemTap with a self-built kernel:
- In item #1 ("Install systemtap..."), link to the proposed "Install
SystemTap" page.
- In item #2 ("Systemtap needs to be able to use..."), the list of
locations needs to be reformatted so you can tell where one pathname
ends and the next begins.  Also consider replacing "uname -r" with
"VERSION" in these pathnames -- the " -" in the middle of a pathname
is especially distracting -- and then explain that VERSION is the
kernel version from uname -r.
- "Failure to do so..."  Failure to do what?

SystemTap GUI Sourceforge: Verify that the software at this site
is the version we want folks to use.

Test Suites:
- Fix capitalization and punctuation.
- In "later version that 20th March", s/that/than/
- s/Note that that/Note that/
- What does INSTALLTREE specify?
- Describe how to run an individual test.
- Remove the reference to the Get Involved page.

TapsetStatus: This needs to be updated.  In particular, some of
the indicated maintainers are no longer on the team.

SystemTap/Dtrace Comparison: I skipped this.

SystemTap GUI/Chime Comparison:
- "Who knew - systemtap has a gui?"  Cute, but no longer apt,
given that there's a link to it elsewhere on this wiki page.
- "Ongoing evolution" is no longer very  rapid.
- dynamically generated scripts: I don't this will happen "soon,"
if at all.
- remote client: This has been demoed, but the authentication needs
work.

-- 
           Summary: Web site mega-review
           Product: systemtap
           Version: unspecified
            Status: NEW
          Severity: normal
          Priority: P2
         Component: documentation
        AssignedTo: systemtap at sources dot redhat dot com
        ReportedBy: jkenisto at us dot ibm dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=6751

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.