docs.rst 4.3 KB

  1. Writing Documentation
  2. =====================
  3. New documentation should fit well with the rest of Elgg's docs.
  4. .. contents:: Contents
  5. :local:
  6. :depth: 1
  7. Testing docs locally
  8. --------------------
  9. Elgg has a `grunt`_ script that automatically builds the docs, opens them in a browser
  10. window, and automatically reloads as you make changes (the reload takes just a few
  11. seconds).
  12. .. code:: sh
  13. cd path/to/elgg/
  14. npm install
  15. grunt
  16. It's that easy! Grunt will continue running, watching the docs for changes and
  17. automatically rebuilding.
  18. .. _grunt:
  19. Follow the existing document organization
  20. -----------------------------------------
  21. The current breakdown is not necessarily the One True Way to organize docs,
  22. but consistency is better than randomness.
  23. intro/*
  24. ^^^^^^^
  25. This is everything that brand new users need to know (installation, features, license, etc.)
  26. admin/*
  27. ^^^^^^^
  28. Guides for administrators. Task-oriented.
  29. guides/*
  30. ^^^^^^^^
  31. API guides for plugin developers. Cookbook-style. Example heavy. Code snippet heavy.
  32. Broken down by services (actions, i18n, routing, db, etc.).
  33. This should only discuss the public API and its behavior, not implementation details or reasoning.
  34. design/*
  35. ^^^^^^^^
  36. Design docs for people who want to get a better understanding of how/why core is built the way it is.
  37. This should discuss internal implementation details of the various services, what tradeoffs were made,
  38. and the reasoning behind the final decision. Should be useful for people who want to contribute and
  39. for communication b/w core devs.
  40. contribute/*
  41. ^^^^^^^^^^^^
  42. Contributors guides for the various ways people can participate in the project.
  43. appendix/*
  44. ^^^^^^^^^^
  45. More detailed/meta/background information about the project (history, roadmap, etc.)
  46. Use "Elgg" in a grammatically correct way
  47. -----------------------------------------
  48. Elgg is not an acronym, so writing it in all caps (ELGG or E-LGG) is incorrect. Please don’t do this.
  49. In English, Elgg does not take an article when used as a noun. Here are some examples to emulate:
  50. * “I’m using Elgg to run my website”
  51. * “Install Elgg to get your community online”
  52. When used as an adjective, the article applies to the main noun, so you should use one. For example:
  53. * "Go to the Elgg community website to get help."
  54. * "I built an Elgg-based network yesterday"
  55. This advice may not apply in languages other than English.
  56. Avoid first person pronouns
  57. ---------------------------
  58. Refer to the reader as “you.” Do not include yourself in the normal narrative.
  59. Before:
  60. When we’re done installing Elgg, we’ll look for some plugins!
  61. After:
  62. When you’re done installing Elgg, look for some plugins!
  63. To refer to yourself (avoid this if possible), use your name and write in the third person.
  64. This clarifies to future readers/editors whose opinions are being expressed.
  65. Before:
  66. I think the best way to do X is to use Y.
  67. After:
  68. Evan thinks the best way to do X is to use Y.
  69. Eliminate fluff
  70. ---------------
  71. Before:
  72. If you want to use a third-party javascript library within the Elgg framework, you should take care to call the ``elgg_register_js`` function to register it.
  73. After:
  74. To use a third-party javascript library, call ``elgg_register_js`` to register it.
  75. Prefer absolute dates over relative ones
  76. ----------------------------------------
  77. It is not easy to tell when a particular sentence or paragraph was written, so relative dates quickly become meaningless.
  78. Absolute dates also give the reader a good indication of whether a project has been abandoned, or whether some advice might be out of date.
  79. Before:
  80. Recently the foo was barred. Soon, the baz will be barred too.
  81. After:
  82. Recently (as of September 2013), the foo was barred.
  83. The baz is expected to be barred by October 2013.
  84. Do not remind the reader to contribute
  85. --------------------------------------
  86. Focus on addressing only the topic at hand.
  87. Constant solicitation for free work is annoying and makes the project look needy.
  88. If people want to contribute to the project, they can visit the contributor guide.
  89. Internationalizing documentation
  90. ================================
  91. When you change documentation, remember to update the documentation translation
  92. templates before you commit:
  93. .. code:: sh
  94. cd docs/
  95. make gettext
  96. For more information, see