Editing

Editing the Wiki

Yeah! You implemented a new feature! You found a way to do a certain thing using existing hard and software? Maybe you hacked together a neat machine using a Hexabus protoyping board! Or did you use Hexabus devices to do something cool?

Share your knowledge in this Wiki using the power of editing!

But please read this article before doing so. It contains some pieces of information you might find useful in order to keep the wiki nice and tidy.

---

tl;dr (Re)move outdated information, link to new articles so people see them, use git and grep.

---

Long version:

• Don't be afraid to change, delete or move stuff!
  • If you made a change that makes some information obsolete (say, you implemented a new version of hexaswitch that's much cooler than the current one), then change the pages about the old version, or write a page about the new version and remove the old pages.
    • If you really think the old information is still necessary, add a note to the old page: "This page is obsolete. Please read (link to my new page) to find out how things are done now"
  • If anything you do changes the order in which things are done, move stuff around. Cut and paste paragraphs, change links, do whatever is necessary to keep things in the right order!
    • For example, you made a new wireless router that makes the USB Stick in the PC obsolete in default setups, but still useful in some cases. Then you should think about how to rearrange articles so that this gets clear: "Yeah, you can use the USB stick, but if you want to be cool, do it like this..."
  • Don't be afraid to change too much! The Wiki has a history feature so we can always restore an older version.
    • If you find out you deleted something that's still important, you can restore an older version. If you need just this one piece of information that you accidentally deleted, you can have a look at an old version of a file and copy whatever you need from there.
• Don't be afraid to change, delete or move stuff!
  • The wiki will never be perfect. You might find stuff that's wrong, or in the wrong place, or outdated.
  • If you have the time, and you can come up with a way to change stuff, please do so.
  • Move things that you think are in the wrong place. Delete outdated stuff if it might confuse people. Update outdated articles if you know what has changed.
  • Should you have made an edit that not all can agree upon (for example removed information that might still have been necessary to somebody), we can still use the Wiki's history to restore things to the way they were.
• Make your new article visible!
  • Most of the time it's best to just put a link in the appropriate section of the Home page.
  • If the page you added is only needed in a very special case, then you can put a link to it on one of the sub pages.
  • Please don't make "orphan" pages which can only be found through the "Pages" page!
• Think about the reader.
  • At the moment, this Wiki is the only source of information about the Hexabus. It is used by first-time visitors trying to find out what Hexabus is about, by users who have just got their first Hexabus toys, and by people who have been playing with their toys for a while.
    • Keep this in mind.
    • What group of readers is your target audience?
    • Does this target audience understand what you are writing?
    • Do they find the article when they should read it?
    • For example, it's no use throwing articles about the inner workings of the firmware at a user who has not figured out how to ping their Hexabus devices yet.
• The Wiki can be used as an idea dump, sketchbook, brainstorming tool as well. But don't confuse visitors!
  • It's nice to just dump ideas onto a page so you can arrange your thoughts, find out what you really want to implement, how to do things, etc.
  • But if you do so, please mark the pages you used for this accordingly. ("This page contains some brainstorming notes from the development of Hexafisch")
    • A new user might stumble upon your page and be very confused by your noncontiguous notes if they look like or are linked to like "real" documentation.
• Use git. Use a text editor. Use grep.
  • The Wiki is a git repo!
    • You can access it at https://github.com/mysmartgrid/hexabus/wiki/_access.
  • Once you have a copy of the Wiki-repo on your computer, you can edit it using your favourite text editor. There might even be a syntax highlighter available... (http://www.vim.org/scripts/script.php?script_id=1242 for example)
    • This makes editing much more convenient. You can have multiple tabs open for several pages, rename things much more easily, and you can combine several "edits" into a single "commit" which keeps the wiki history a bit cleaner.
  • You can upload more than just text files to the Wiki using git (PDFs, images, ...)
  • You can use grep and other useful tools!
    • When changing stuff, this is very useful to ensure consistency! (nothing is more annoying than trying to look up a piece of information in a wiki, and finding two conflicting statements...)
  • You can git push and git pull the wiki.
    • It works just like with a normal git repo: Git pull downloads the most current version to your PC, and git push uploads your commits to github. The web interface of the Wiki on github always displays the most current version of the master branch.
    • Careful: Please don't use branches when not absolutely necessary. While it does work, it might break the history view in the web interface (crediting another hundred edits to you, for example).