Closed Bug 151101 Opened 22 years ago Closed 19 years ago

Documentation needs a roadmap

Categories

(Developer Documentation Graveyard :: General, defect)

Product:
Developer Documentation Graveyard
Component:
General
Type:
defect
Priority:
Not set
Severity:
blocker

Tracking

(Not tracked)

Status:
RESOLVED WONTFIX

People

(Reporter: WeirdAl, Assigned: endico)

References

(
URL
)

Details

Attachments

(3 obsolete files) 

The current status of our Documentation is not good.  In many cases, we're doing
documentation on an as-requested, as-manpower-makes-it-possible basis.

I'm cc'ing Mitchell Baker because, at the Nov. 9, 2001 Developer Day conference
in Mountain View, CA, I attended a meeting she ran for business use of the
Mozilla suite.  There, the discussion quickly turned to show that lack of
effective documentation is the number one concern of business, the number one
factor stopping companies from using our code to develop new products.  I don't
have any notes off the top of my head for that meeting (my notebook is buried
elsewhere), but hopefully Mrs. Baker can provide some notes and feedback from
the community.

One of the topics I remember from that meeting is that Bugzilla was not
considered a totally appropriate tool for tracking documentation scenarios.  

What we really need is a roadmap for what documentation is most badly needed by
the community at large, how difficult that is, etc.  We currently have 198 bugs
(this is #198) in Documentation that are open.

Here's some feedback from #documentation and n.p.m.documentation:
<quote>
<DavidGerard> * find out what docs do exist and catalog them. there's tons o'
stuff but you just can't find it on moz.org unless you know what you're looking for.
* once we have the catalog, work out a list of holes in it (this does not
preclude listing holes before then)
really want to get Ian Oeschger's opinions on it though - he did the current
helpfile (it's the NS 6.2 help vaguely adapted I think) and would need
convincing to change formats etc

<grayrest> I really think we have most end user documentation covered between
the help files and the FAQ
it just needs to be consolidated and processed for end users
we need a couple embedding tutorials, they exist elsewhere, but they'd be nice
to have on m.o

(n.p.m, Brian Heinrich, "Where are we at?", 11-Jun-02, 20:53pm)
Interestingly (or not), it seems that we're heading in several different directions.

  1. Reworking the current help file.
  2. Reworking the existing mozilla.org documentation.
  3. Maintaining/expanding http://mozilla.org/start/1.0/faq/ (and,
     possibly, reworking http://mozilla.org/start/1.0/guide/).

Well, OK, I'm cool with that, but we need to have some sort of structure in
place.  There is obviously going to be overlap amongst the various parts, which
is fine, but I'd hate to see overlap in the actual content generated.  So we're
going to have to figure out just who's gonna do what. 

<grayrest> in short, we need writers for documentation and need them pretty
fast. We need to develop a roadmap to guide those developers and have someone
wear the documentation hat so all us documenter rats can dance for the pied piper.

<DavidGerard>also note that new users are showing up in npm.doc saying they want
to contribute but they're writers, not coders. a volunteer resource that may or
may not be ripe for the plucking!
if we have little things we can throw them at, it will rapidly sort out which
ones are any use and which ones aren't.
</quote>

This bug is being filed primarily to track the creation of a roadmap document. 
Once we have a roadmap we can agree on and post to m.o, we can mark this bug FIXED.

I will momentarily file a bug for a DocWeek, blocked by this bug.
Blocks: docweek
I should know better than to file new bugs at blocker level and assign them to
someone else.  Taking.
Status: NEW → ASSIGNED
Really taking.
Assignee: endico → jscript
Status: ASSIGNED → NEW
Just posted news://news.mozilla.org:119/slrnage1gk.44k.fun@crushed.velvet.net
to n.p.m.doc and n.p.m.general to start a thread of ideas for possible tasks for
the roadmap.
This is my suggested first draft for the roadmap; feel free to make comments
and/or changes as you see fit.
Alex Savulov and I have been working on documentation policies and a roadmap
specifically to save our internal developer-level documentation.  Some of these
ideas may be applicable to the overall roadmap, but they will certainly affect
1/5 of the proposal at the least :)  Here is the outline and a couple of
proto-docs that aren't anywhere near complete.  Suggestions welcome.

We have two sections of developer-level documentation in Mozilla, the high-level
and the API documentation.  The high-level documentation suffers from bitrot and
a lack of people writing it, and the API documentation suffers mainly from
nobody doing it.  The lack of people writing high-level documentation,
furthermore, is partly due to a lack of knowledge of what to write :)  Both of
these problems can be solved, and here is how:

1. Require a developer to write a simple "technote" when design or architecture
changes.  Nothing fancy, just get the information out on paper.
2. Have writers come through and incorporate technotes into high-level
documentation as changes come through.
3. Require developers to write API documentation when they change or add public
interfaces, member vars, etc.  They may complain, but by God when you write
Mozilla code you put comments in that code.  r= and sr= enforce this and #1.

We have the idea to make the technotes system be a PHP-documentation-like system
of developers adding comments to documents so that people who are reading the
doc can see the comments as addendums, but this is an implementation detail. 
There is a Zope site dedicated to Mozilla that we could use to do this now,
though.  I always like solutions that don't require new development.

Proto-docs that may go away and will definitely change:
http://www.johnkeiser.com/mozilla/Document_Map.html
http://www.johnkeiser.com/mozilla/API_Documentation.html

WeirdAl and I had a discussion about how this might be applicable to end-user
documentation.  It may be possible to have a PHP-documentation-like system for
them, too, to comment in the same way, but there are problems of scale
there--there are so many people who might comment that it is unclear whether
it's the right solution.
It seems like WeirdAl, jkeiser, /et al./ are getting a physical (OK, /virtual/)
backbone in place.  The actual documentation process still isn't well defined,
however.

On the one hand, it does make sense to wait till the backbone is in place, since
that will delimit the scope of what can be done with documentation; on the
other, we should probably be starting to look at putting a functional structure
in place.

David and I are already involved (in both writing and editing capacities), and
there have been others who have indicated interest in n.p.m.d11n:   Melanie
('calligraphy') Burrett seems interested in the actual writing process; Nigel L.
apparently has experience as a U. N. editor, and would seem to be a good
resource when it comes to documentation in broken English (I've done similar
work as a tutor, primarily with students from Hong Kong and Malaysia); and Amy
Yancey has also volunteered her services (she would seem to be a good re-write
resource).

The interest (at least for the moment) is there; we just need to figure out a
way to make use of it. -- We need to encourage people, but also need a framework
in place,

[Personal input can be posted here (which will be sent to my Bugzilla addy) or
sent directly to me:  'Brian Heinrich <wordsmyth@myrealbox.com>' -- an address
set up for writing-oriented projects (please respect this, 'k?).]

Brian
A few ideas for "functional structure" for those working on end-user docs.  You
get people to work on docs by giving them ideas of what to work on, making it
easy for them to work on it, and giving them rewards when they do.  And above
all that you get people to work on docs by advertising.

A document map and a suggested list of HOWTOs, along with 2 or 3 HOWTOs already
in place, would go a *long* way towards jumpstarting the process--it helps make
it easy for people to work on it.  It's not enough though.  You also have to
advertise.

And did I mention that you have to advertise?  Use all the hysterical techniques
that you can think of--"the sky will fall if Mozilla documentation remains in
the state it is in!  Only YOU can save us, Obi-Wan Joe User!  You are our only
hope!"

As to rewards, one potential idea is the gold star system--this could be useful
to users too.  When someone writes a doc, the reviewer assigns it stars.  1 or 2
means it shouldn't have been on the system at all, 3 means it's the bare
minimum, 4 means pretty good, and 5 means it's the bee's knees.  We can support
an "author page" in the doc catalog that shows all docs written by a particular
author in summary, so that they can link to it and show off :)
I'm a little lost as to how all this stuff applies to the roadmap draft I drew
up.  I filed bug 151952 for tracking suggested tools -- if a tool is rejected as
RESOLVED WONTFIX or RESOLVED FIXED, it doesn't matter to the roadmap too much. 
Certainly we can mention the tools in the roadmap.  As for specifics of what
needs documentation, that's also very important, and we should probably link to
it in the roadmap.

This bug is for the roadmap; what specifically do you want added or changed in
the roadmap?
Depends on: 152208
One consensus I'm hearing pretty clearly is to merge "Mozilla internal
developers" and "Mozilla-based product developers" into one category.  Another
is that the Nuts & Bolts should be like an annotated LXR, possibly like the php
manual -- but what about perhaps doing like Tinderbox does, having little stars
with comments as tooltips right in the code?  That way, someone doesn't get lost
going to the end of the document.
Apologies:  I just broke my own cardinal rule in comment 8.
Guys:

I see here a tendency to split the disscutions in too many bugs (this, bug
151952, bug 151961, bug 152220, bug 151102, bug 152208). It won't work at all,
we are going to lose track of what we are doing and we cannot coordinate
ourselves. Trust me, after a week of looking at hundreds of bug mails and
dealing with all this 6 digits numbers is not fun at all to have this
documentation disscutions in bugs.

Jkeiser is working on having a Zope system work for us. This will (hopefully)
bring a little bit more coordination in what we do. Yes, we will also have the
PHP doc like comments. We can use it in the initial roadmap drawing activity and
if it turns out reliable and easy to use we can continue using it.

Here is a thing that we definitively need: a coordinator. If everyone is working
in all directions, starting little projects that get abandoned after a while
resulting in old an badly updated documents, we will get what we already have:
an outdated, hard to browse documentation. I know, everyone has great ideeas and
would like to see them realised, but since we work in a big team, we need to
synchronize our actions and work focused in one direction. We (Jkeiser and me)
have also spent some valuable hours in defining what is to be done and it would
be unproductive to drop that away.

Thus, I would propose to organize the team before we start dealing with what is
to be done and which tools are to be used or modified. 

I would suggest to have Jkeiser as a coordinator (although he has a bunch of
other things to do too). The reason i'm doing this is that Jkeiser has a very
good reputation within the big mozilla team (inside and outside Netscape), is
dedicated to this effort, and has really good ideeas. It is also strategical
very desirable to have him leading this effort since from inside Netscape you
can reach more important resources faster than from outside. Since we both are
at the same location, I can work with him directly when he needs someone to
help. Another reason is that we in the layout team desperately need this
documentation done and I personally think that it would be the biggest part of
it. We plan to redesign parts of the layout and need to document the existing
architecture asap.

So everyone please see if this is a reasonable proposal and let me know by
commenting on this bug or mailing me directly. Let's set a week from now as the
deadline for feedback on this proposal (that is 06-24-02 1:00pm bugzilla time
:-). Please spread the word and CC anyone here that might be interrested. I will
also send this as a mail to the CCs that I see on the bugs listed above.

Thanks a lot!

*** JKEISER FOR PRESIDENT :-) ***
In defense of the bugs Mr. Savulov mentioned (all of them filed by me...)

The goal of the bugs is to keep each of them focused on a specific topic, with
more general discussions in #documentation and the newsgroup.  I agree a couple
of them (notably this one) have gotten a little off-topic, and I'm trying to
keep them on track.

I'll be posting to n.p.m.docs a listing of the bugs we currently have now and
why we have them.
Since comment 11 was sent by email to a wider audience than just the cc: list of
this bug, I replied to it by email.  Here's what I wrote:

I don't think cathedral-style (rather than bazaar-style) organization of
documentation writing is useful for Mozilla developer documentation.
Developer documentation usually needs to explain how the code works, why
it works that way, and what the disadvantages of the current
implementation are.  Limited API documentation at least needs to explain
how to use the API correctly.  Someone who isn't an expert on the code  
can't write useful developer documentation.  Thus, the people who we
want to write developer documentation are the ones who are already doing
development (and who are thus very busy).

If we come up with a grand plan for the ideal documentation structure,
we'll never implement it.  If we want to do something realistic, we need
to encourage people to write more documentation where it is most useful.
Areas where it is most useful are those
 * where the substitutes for documentation (such as information transfer
   via discussion and code review) are the poorest or most time
   consuming (e.g., general XPCOM coding practices that are better
   explained once, or how to use frequently used (or frequently misused)
   APIs),
 * where we feel that too much information is known only by too few
   people (because the few are at risk of leaving the project or because
   the many need to gain a more thorough understanding of the code)
   
How do we accomplish this?  We should encourage people to write (or
revise) the documentation that they think is most useful, given the
documentation that already exists, and we should encourage people to
write the documentation that other developers are asking for.  For  
example, the slides from waterson's Layout tech-talk should satisfy a
bit of the demand for general layout documentation that a number of  
people have been asking for.  Likewise, I'm trying to work on some   
general documentation of the style system because I'd like more people
to understand it, but I've been focusing on the parts that general
layout engineers run into and get wrong more often (style context 
management).

I don't see how people other than the maintainers of the code are going
to understand what code is commonly misunderstood and what code people 
have questions about most often.  Thus, I don't see how a documentation
roadmap (certainly one designed by non-experts, as most of the
documentation discussion to date has been, and perhaps even one designed
by the core developers) would be useful.

(That said, I'm also somewhat confused about the purpose of bug 151101.
It was originally filed on the "Mozilla Developer" component, but the  
initial comment looks like it was really about end user documentation.)
So dbaron thinks the roadmap is primarily an end-user docs roadmap.  That's fine
with me; what do we need to say for a developer docs roadmap?
Let's go ahead just require developer docs as suggested by Jkeiser and have
somebody organize it when it gets to a critical mass. Of course that critical
mass needs to be relatively soon, but we can dive in there only if needed. I'd
also agree with the roadmap being better fitted to end-user (including web
developers) docs. The only suggestion I have is to keep developers of products
based on Mozilla and internal developers separate -- because of the depth of
code knowledge required for both. The former only needs to go down to the API
level, while Moz hackers need to know everything from the inside out. Anyhow,
I'm down with the roadmap. Suggested full speed ahead. 
That was pretty much the ideea. Have devs writing the docs and have a kernel of
guys to put everything in place. Afaik we can go with Jkeiser at the steering
wheel. He spent already time with all kind of preparations so we can act in a
consistent way.
Based on feedback I've received so far, here's the second version.  Note that,
among other things, it's aimed primarily at the documentation efforts for end
users.

Do we need a roadmap for the other categories?
Attachment #87710 - Attachment is obsolete: true
A. Vincent:

let's wait until tomorow so we can try to forge your road map with the document
we (jkeiser and me) prepared for the launch of the documentation effort. I'm not
sure yet how far jkeiser brought that document but from what I know is pretty
detailed and near completion. Jkeiser is not only working on that tool (zope),
but he also puts together the plan for the documentation process. We will try
then to put everything together and have a "one and only initiator document"
from where we can start the detailed planinng. Maybe we will decide then to
split the effort in the developer / embedder / plugin developer / user
documentation. How does that sound?
I'm game.  :) Why don't you join us in #documentation?
A bug is not the correct place for discussion of a documentation roadmap. The
newsgroup is the correct place, where discussions are threaded.

> We have begun work on a catalog, similar to dmoz.org, for Mozilla documentation.

What, like http://www.mozilla.org/catalog/ (maintained by ksosez)?

You need to know what is available currently before you decide what needs
writing next.

> # The specifications are now awaiting feedback from the Mozilla.org developer 
> and user community at large, and approval from a higher power (like Steve 
> Rudman).

As far as I am aware, Steve Rudman does not have any special "higher power" with
relation to Mozilla documentation. Mozilla module owners (of which Steve is not
one; there isn't one for documentation) are jobs independent of someone's day job.

Steve may well be a great person to have on board for whatever ideas you have,
and I'm sure he can offer a lot of help, and that's great. But any plans you
come up with don't need his approval.

> DocWeek

You need to get buy-in for this idea, otherwise it'll be a damp squib. When you
have a concrete proposal, run it past staff@mozilla.org . But remember,
developers have other priorities, and neither we nor you can force them to write
documentation.

Please post this roadmap on a website somewhere, so its URL doesn't change when
you update it, and continue this discussion in the newsgroups.

Gerv



> You need to get buy-in for this idea, otherwise it'll be a damp squib. When you
> have a concrete proposal, run it past staff@mozilla.org . But remember,
> developers have other priorities, and neither we nor you can force them to write
> documentation.

I cannot think of a more perfect summation of how documentation is misunderstood
and devalued. Saying the above is the same thing as saying, "We cannot force
developers to write good code." Yes, you CAN. And you DO by implementing QA
processes and accept/reject processes. Changing the internal processes may not
be easy, but to simply say, "We can't force developers to write documentation"
virtually ensures that the low-level docs will never be done. This is a
defeatist attitude that gives short shrift to documentation as an entity and
restricts the developer pool by providing no support for newbie developers. It's
kind of like making the bar 200 feet high and then moaning about why you have a
dearth of pole-vault jumpers. I'm surprised to see this in an open-source
project, of all places! The previous idea of REQUIRING a technote for the code
to approved is without a doubt the way to go. 
I'm listening to Gerv, and I agree that discussion in bugs should be kept to a
minimum.  Take this debate outside (to the newsgroup and #documentation, which
hopefully will dump conversation logs to the newsgroup whenever practical).
URI field now reflects a more stable (I hope!) URI for our proposed
documentation management roadmap.  Current draft is the 3rd revision.

Also, to save on bugspam I'll announce new drafts for the roadmap in n.p.m.doc .
URL: http://moz.zope.org/contribute/writin...
Attachment #88069 - Attachment is obsolete: true
Attached file mdp.zip (obsolete) — 
A new roadmap proposal, along with a complete flowchart of
documentation management process.

This proposal practically ignores everything that has been suggested
except for a documentation catalogue.
Blocks: docathon
What is the progress?
Assignee: ajvincent → endico
Status: NEW → RESOLVED
Closed: 19 years ago
Resolution: --- → WONTFIX
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Component: Documentation Requests → Documentation
Component: Documentation → General
Product: Mozilla Developer Network → Developer Documentation
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: