[OpenAFS-Doc] State of the documentation presentation?

[Jason Edgecombe]

Hi there,

A couple of people on the openafs-info list responded to my inquiry
about workshop topics. One suggestion was a "state of the
documentation" presentation. I wanted to pose the idea to the doc list
ot get input.

Steven Jenkins had the following to say:
==============================================================

doc/README, doc/man-pages/README summarization would be a start. It
would be helpful to know who is tackling what, and how best to
coordinate with them (e.g., the comments about Simon Wilkinson working
on the Quick Start guide). My assumption is that between now and the
Workshop, you will probably finish out this list of 'no man pages
exist' from doc/man-pages/README:

copyauth
fs cscpolicy
fs memdump
fs minidump
fs monitor
fs rxstatpeer
fs rxstatproc
fs setcbaddr
restorevol
rmtsysd
vldb_convert
vos clone
vos setfields
vos shadow
vsys

so to me, the interesting questions are

- what's next?
- what kind of skillset is needed to help with the docs on which part?
- who is actively doing work on the docs, and how should people
coordinate with you (or whomever is actively doing things)

=======================================================

I wouldn't feel comfortable about presenting on the documentation without consulting with Russ and Simon.

comments?

Sincerely,
Jason

[Jeffrey Altman]

Post by Jason Edgecombe
Hi there,
A couple of people on the openafs-info list responded to my inquiry
about workshop topics. One suggestion was a "state of the
documentation" presentation. I wanted to pose the idea to the doc list
ot get input.

I do not think that "State of the Documentation" is a presentation
in and of itself. The State of the Documentation should be discussed
as part of the OpenAFS status report.

Jeffrey Altman

[Russ Allbery]

Post by Jason Edgecombe
==============================================================
doc/README, doc/man-pages/README summarization would be a start. It
would be helpful to know who is tackling what, and how best to
coordinate with them (e.g., the comments about Simon Wilkinson working
on the Quick Start guide). My assumption is that between now and the
Workshop, you will probably finish out this list of 'no man pages exist'
copyauth
fs cscpolicy
fs memdump
fs minidump
fs monitor
fs rxstatpeer
fs rxstatproc
fs setcbaddr
restorevol
rmtsysd
vldb_convert
vos clone
vos setfields
vos shadow
vsys
so to me, the interesting questions are
- what's next?
- what kind of skillset is needed to help with the docs on which part?
- who is actively doing work on the docs, and how should people
coordinate with you (or whomever is actively doing things)

For the man pages, there are a lot of other issues listed in the README
that do need to be resolved still. I think the fileserver documentation
still needs a lot of work, there's further cleanup required to remove
kaserver references and assumptions, dynroot needs more documentation, and
I think a general check for where we need to mention Kerberos v5 would be
useful.

However, there are two things that really stand out:

* We need to be generating HTML versions of the man pages automatically
and installing them on openafs.org somewhere, and we likewise need to be
generating HTML versions of the current DocBook pages in CVS and
displaying those on openafs.org instead of the old IBM manuals.

* We need to figure out how we're going to maintain the DocBook manuals.

My personal feeling on the latter is that one of the biggest barriers to
entry on DocBook (and one of the reasons why the POD pages have gotten
much more attention) is that DocBook is ginormous and horribly
intimidating. I have no idea what tags to use for common things when
writing in DocBook, and the manuals and references leave me drowning in
too much information.

I would really like to see someone write up a simple DocBook style guide
that duplicates just enough of the DocBook manual to say "here's the basic
structure, here are the tags we actually use, use the following inline
markup tags for the following things, and don't use anything else not
mentioned in this guide." Even a starting point would be great.

Then, once we have that, we need to take a comprehensive pass through the
existing manuals and bring them in line with that style guide. The result
will be something that we can actually update and maintain without being
lost in the necessary tag conventions.

[chas williams - CONTRACTOR]

Post by Russ Allbery
My personal feeling on the latter is that one of the biggest barriers to
entry on DocBook (and one of the reasons why the POD pages have gotten
much more attention) is that DocBook is ginormous and horribly
intimidating. I have no idea what tags to use for common things when
writing in DocBook, and the manuals and references leave me drowning in
too much information.

it seems intimidating at first, but docbook is much easier than it looks.
once i got the hang of the basic conversion from .html to docbook
using tidy, it was pretty easy to edit things. a few things needed
to be hand converted, like notes/cautions, which initially where
converted to single item tables as i recall.

the online version of the docbook manual is pretty handy. that is
all i needed once i got going.

Post by Russ Allbery
I would really like to see someone write up a simple DocBook style guide
that duplicates just enough of the DocBook manual to say "here's the basic
structure, here are the tags we actually use, use the following inline
markup tags for the following things, and don't use anything else not
mentioned in this guide." Even a starting point would be great.

i could do this next weekend if no one objects. given that i did the
conversion i suppose it would make the most sense (and i should ahve
done this at the time). probably the most broken part is the syntax
highlighting. it needs to be consistent and i didnt get everything
consistent. for instance using variable instead of emphasis. these
generally both render the same, but they might not. some things are
probably not using the most efficient table either.

Post by Russ Allbery
Then, once we have that, we need to take a comprehensive pass through the
existing manuals and bring them in line with that style guide. The result
will be something that we can actually update and maintain without being
lost in the necessary tag conventions.

easier said that done of course.