Nov 092006
 

We’re having an interesting discussion in #extdev at the moment about the state of the documentation, and I just want to remind people of this:

  1. If you go looking for something in the docs and can’t find it, please do something about it! At a minimum, file a bug against the documentation.
  2. Better yet, once you find an answer, or a page on another site that provides information, add a stub page to the documentation with your notes. It doesn’t even have to be real documentation. Just throw whatever information you find onto the page. Others will come along and clean it up and improve on it.

You don’t have to be a writer to help us make the documentation better. You just need to take a few minutes and share your knowledge. A simple, quick and dirty brain dump can lead to the addition of vast amounts of documentation.

The fact is that the hard part is figuring out what needs to be written. Once you get the ball rolling, you’ll find that things build up fast.

 Posted by at 4:25 PM

  3 Responses to “Help us help you”

  1. You said:
    “It doesn’t even have to be real documentation. Just throw whatever information you find onto the page. Others will come along and clean it up and improve on it.”

    I totally disagree with what you say: it’s not just the way you said it.
    This sort of “Krusty burger” policy is exactly why I stopped contributing into Mozilla Developer Center. People, anyone, can come into your document and edit/delete/remove/add/change whatever they want without explanation.
    This sort of “mediocrity welcomed” policy, an universal “do as you wish” policy is what makes a documentation become crummy, outdated, not professional and always kinda “nah! it’s good enough for everyone else”.

    I’m sorry. I absolutely and unconditionally believe that Mozilla products, Mozilla users, Mozilla developers and web standards advocacy groups deserve a lot better than mediocrity, complacency, global incoherent thinking, inconsequent + counter-productive documentation development strategy.

    Gérard Talbot

  2. You’re assuming that nobody’s going to clean up the mess. My hiring was intended to help deal with the situation you describe. Now that there’s an actual on-staff technical writer whose job it is, literally, to take the documentation and make sure it doesn’t suck, I’m encouraging people to contribute, no matter what.

    If people who actually know the material can contribute anything, even just basic notes, I (as well as a number of volunteers) can turn it into good, high quality documentation.

    But I have to get the information from somewhere.

  3. Hello,
    “You’re assuming that nobody’s going to clean up the mess.”
    I’m not assuming an hypothetical situation: I’m talking about my experience, what happened, what drove me to stop contributing. I’m talking about a reality, not an assumed-hypothetical future. In one case, modifications done to one document I wrote were assessed to be wrong, incorrect by its author himself and all I got is an invitation to undo *_his_* modifications. A totally incoherent, inconsequent policy. If you srew up, then you are the one who should spend time, efforts to correct what you’ve done wrong. I already had to substantiate and explain (typing emails takes time, you see) how/why the modifications were wrong to begin with. I can not and will not spend endless hours of time, typing, energy trying to document what’s correct in my own documents when others can change anything, anywhere, for no given reason, not even explanations. It’s blatantly absurd. I end up having to spend a crazy amount of time, more time on explaining, justifying than on writing the document itself.

    “My hiring was intended to help deal with the situation you describe.”
    Well, then, good luck with your new work. Having to deal with multiple perspectives, people with different background/experience, with different depths of experience in coding and in edition, people caring for particular – and worthy – issues (like best coding practices, promoting web standards, understanding that a code ought to be portable and the best it can in all circumstances like web authoring) is a thing I have not seen enough of at MDC

    “Now that there’s an actual on-staff technical writer whose job it is, literally, to take the documentation and make sure it doesn’t suck, I’m encouraging people to contribute, no matter what.”
    Why not try to make the first draft the right, correct one? What’s the best coherent policy on such issue: to have 2, 3, 5 even 10 reviews whose efforts are neutralized, countered on and on or have 1 person who can write good stuff from the beginning? What’s the most efficient way here? Which policy will not discourage good writers, people with a good mastery of the knowledge/experience they have? Why not establish coding guidelines, editorial guidelines, etc.? How about meeting edition requirements when writing a document?

    Compliance with known web standards is already a known and well establish requirement which nobody should even be questioning at MDC. Then why do I still have to defend, explain, promote, etc that code examples must be using valid markup code, strict DTD, valid CSS code, clear separation of structure and presentation, etc. code that anyone could copy and then paste into a webpage and to see it work?
    Some webpages at MDC already have hundreds validation markup errors: I am not surprised.

    I have clearly and repeatedly said that MDC success must rely on good quality of documents, good technical writing, good coding practices (from a web standards perspective) and interactive examples. MDC is not a success when it relies on a “do-as-you-wish” editorial openness, “whatever-you-write-is-fine” attitude and “let the others worry about your screw up” attitude. Quality is always about meeting standards, achieving respect for norms, reaching requirements, about an approach promoting perfectibility. Quality is not the result of an approach based on a “whatever-you-do-is-fine” attitude.

    Your hiring proves that not everyone should get involved in writing in MDC documents. Your hiring proves that you are an alibi, some sort of a crouch to a inconsequent + counter-productive documentation development strategy.

    Gérard Talbot