Style guide

From EDM2
Jump to: navigation, search

Note that this is just intended for "Wiki" articles or pages, a more general article or an article republished from another source has much more freedom when it comes to formatting.

In general a Wiki page should start with an introduction to the material and then followed by more detailed information dissected into subsections as much as possible. The text below the introduction should be contained in an order of diminishing usefulness to the end user of the page and not the order of diminishing importance, simply because the concept of importance is far too dependant on the eye of the beholder.

This can mean that on a wiki page that is a listing of a specific software tool or other product:

  • General description
    • Features if deemed necessary
    • History
      • Version
      • Detailed feature sections, especially if no feature section after general description. Optional
        • Links and or publications
          • License
            • Author

While for a computer language we might see for instance:

  • General description of the tool
    • OS/2 implementations and tools
      • DOS implementations and tools
      • WinOS/2, Java, JavaScript and other non-native implementations that run on OS/2 with some help.
        • Links and or publications
          • Standards
            • History

Note that in this case the history has been moved from the top of the page to the bottom, the reason for this is the principle of diminishing usefulness. While the history of a computer language is dead interesting to certain types of nerds and there is a certain amount of practical knowledge contained in such essays, it is not of a lot that concerns the day to day user of the language. With a software compiler however quite a lot of practical information may be contained in its history, for instance the compatibility of certain versions with certain targets, the perceived quality of certain versions, soon and so forth.

Is the software current?

There is a valid difference between stabilised and discontinued software when it comes to commercial software, commercial software may be "stabilised", i.e. the publisher or author will not perform any further development work on the program except perhaps minor fixes but continues to sell and support it and is therefore to be considered current. This is different from how things that are perceived for freeware and open source software where if something that has not been worked on for a few years is considered dead, no matter how suitable for the task it is, this is especially the case if the software sees work on other platforms but the OS/2 version is not updated.

History

If the tool is mostly of historical interest it is perfectly acceptable to have the history in the introductory/general section at the beginning of the article, even though it is good practice to separate the history into a subsection.