Our principles of writing and reading documentation — 刚写的撰写文档与读文档的原则

To encourage our gurus to contribute docs to their code and whole project architecture, I tried to provide some guidelines for them.

How to write and how to use the documentations?

To Writers:

  • It’s going to be two sorts of readers for your documentations
    • Newbies
      • Make sure your documentations are as simple as possible to understand
      • Try not to include everything into a single documentation page. Try separate them into small pieces, independent pages. So that our new comers could find relative docs on working on new tasks
      • You need to train them according to the docs you have composed face to face. And after that, the docs would be a good place to go if they forgot what you have just said.
      • Try to update the docs timely while training them, or they will come to you again and again since the docs are out-of-date and confusing.
      • If you want to distribute new tasks to them, you have to tell them where the docs are, so that it would not be too time consuming with communication/knowledge transfer among you. And more important, they would not disappoint you anyway.
    • Other sophisticators
      • Try transfer your perspectives and insights with the components you have done to other gurus. They would appreciate you and like you.
      • Some days you may have some family urgency. It would be much better and easier for our project if you could leave a piece of  docs for reference for other gurus, so that they could handle your own issue crisply.
  • Sign on your name on the docs please.
    • Someone would come to you if they find any issues.
    • It’s your own boy. Take care it please~~

To Readers

  • Never rely on these docs if you could count on the authors. So, go face to face to them and just take the docs as references if you forget anything.
  • Due to resource scarcity, the docs may be out of date. In that case, ask the author to update it please and both of you would be joyful.