Skip to content

Writing a good wiki page

Vicky Vergara edited this page Apr 5, 2015 · 7 revisions

Overview or What is this?

When presenting information in this wiki, we need to think on how information should be presented to a reader. We are trying to standardize the way a wiki page os written for pgRouting. You can think of this as a simple outline for presenting information in documents presentations, technical specification, etc.

Who should read this? or Why do I care?

  • If you are a developer writing about a function, and need to write a wiki page about your function.
  • If you are a documentation writer, and you missed some crucial concepts in the last release.
  • If you are a tutorial developer, and you need a wiki to propose another tutorial
  • If you are a GSoC (Google Summer of Code) Students, you want to keep your weekly reports in the wiki

How does this work?

Essentially, just like this document! You present information using this simple outline (the titles may vary).

  • Overview or What is this? (1-2 sentences)
  • Who should read this? or Why do I care? (1-2 paragraphs)
  • How does this work? (an overview or work flow)
  • What do I have to do to make this work? (a detailed description of each step)
  • more details and examples as needed

What do I have to do to make this work?

  • Start with this outline and think about what you need to present, who is your audience, and what they need to know.
  • Expand the outline with additional sub-bullets for the major points you need to cover.
  • Write up each section and add additional sections for details and examples as needed.
  • Have someone to review it and ask questions about what they do not understand.
  • Then update it as appropriate to clarify the questions.

Recomendations

  1. Don't use, long paragraphs. [example1] (Writing a good wiki example1)

  2. Allways have a link to the next topic like [example2] (Writing a good wiki example2)

  3. Allways have a link to the main topic unlike [example3] (Writing a good wiki example3)

  4. Allways start your sub-files with the same name

    • Writing a good wiki page
    • Writing a good wiki example1
    • Writing a good wiki example2
    • Writing a good wiki example3

Allways have a link to the main pgRouting wiki

[pgRouting Wiki](https://github.com/pgRouting/pgrouting/wiki)
Clone this wiki locally