Closed
Bug 151101
Opened 22 years ago
Closed 19 years ago
Documentation needs a roadmap
Categories
(Developer Documentation Graveyard :: General, defect)
Developer Documentation Graveyard
General
Tracking
(Not tracked)
RESOLVED
WONTFIX
People
(Reporter: WeirdAl, Assigned: endico)
References
()
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.
Reporter | ||
Comment 1•22 years ago
|
||
I should know better than to file new bugs at blocker level and assign them to someone else. Taking.
Status: NEW → ASSIGNED
Comment 3•22 years ago
|
||
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.
Reporter | ||
Comment 4•22 years ago
|
||
This is my suggested first draft for the roadmap; feel free to make comments and/or changes as you see fit.
Comment 5•22 years ago
|
||
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.
Comment 6•22 years ago
|
||
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
Comment 7•22 years ago
|
||
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 :)
Reporter | ||
Comment 8•22 years ago
|
||
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?
Reporter | ||
Comment 9•22 years ago
|
||
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.
Reporter | ||
Comment 10•22 years ago
|
||
Apologies: I just broke my own cardinal rule in comment 8.
Comment 11•22 years ago
|
||
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 :-) ***
Reporter | ||
Comment 12•22 years ago
|
||
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.)
Reporter | ||
Comment 14•22 years ago
|
||
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?
Comment 15•22 years ago
|
||
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.
Comment 16•22 years ago
|
||
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.
Reporter | ||
Comment 17•22 years ago
|
||
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
Comment 18•22 years ago
|
||
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?
Reporter | ||
Comment 19•22 years ago
|
||
I'm game. :) Why don't you join us in #documentation?
Comment 20•22 years ago
|
||
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
Comment 21•22 years ago
|
||
> 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.
Reporter | ||
Comment 22•22 years ago
|
||
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).
Reporter | ||
Comment 23•22 years ago
|
||
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 .
Reporter | ||
Updated•22 years ago
|
Attachment #88069 -
Attachment is obsolete: true
Comment 24•22 years ago
|
||
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.
Comment 25•22 years ago
|
||
To view the attachment directly, go to jar:http://bugzilla.mozilla.org/attachment.cgi?id=110859&action=view!/index.html
Comment 26•22 years ago
|
||
Comment on attachment 110859 [details] mdp.zip http://www.geocities.com/stolenclover/backstage/mozilla-org/docs/mdp/roadmap.ht ml
Attachment #110859 -
Attachment is obsolete: true
Reporter | ||
Updated•19 years ago
|
Status: NEW → RESOLVED
Closed: 19 years ago
Resolution: --- → WONTFIX
Updated•17 years ago
|
Component: Mozilla Developer → Documentation Requests
Product: Documentation → Mozilla Developer Center
Updated•12 years ago
|
Component: Documentation Requests → Documentation
Updated•12 years ago
|
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.
Description
•