Author Best Practices

From Texas Instruments Embedded Processors Wiki

Contents 1 Purpose 2 Extensions 3 Categories 3.1 Subcategories 4 Guidelines for adding content 5 Guidelines for adding attachments 6 Syntax Guidelines 6.1 General Syntax Recommendations 6.1.1 Examples 6.2 Links to Other Embedded Processors Wiki Articles 6.3 Links to TI literature/documents 6.4 Links to TI Product Folders 7 Renaming articles 8 Creating new device family articles

Purpose

This page was created to archive the best practices that authors should use in adding content to the TI Embedded Processors Wiki, and, really, any other MediaWiki that one might encounter. Wikis are organic, and continue to grow in many ways. Without some guidelines and the conscientiousness of the contributors, the information on the wiki can quickly get unwieldy. The TI Embedded Processors Wiki Administrators encourage you to contribute to the Wiki. We also encourage you to help us develop these Best Practices and use them to maintain the wiki as a valuable source of information.

Extensions

Extensions are frequently added to the wiki in order to make it easier to organize content and gain maximum reuse of existing content. Be sure to continually check out the WikiExtensions page for updates on the extensions that have been installed and the proper way to use them.

Categories

As a general rule, categories should be broad. Before creating a category, consider how many different articles will fit under it. If the answer is < 10, perhaps this is not an effective category title. If the answer is > 50, this is probably a very good category title.

Categories are designed to help the user narrow down the articles that they are interested in to a manageable number. If the number of categories becomes unwieldy, the categories themselves are not useful. A better method is to make the article a member of multiple categories. For example, an article about an H264 Decoder example, using DSP/BIOS for the 64x+ device would be better as a member of the H264, DSP-BIOS and 64x+ categories, rather than a separate H264_DSP-BIOS_64x+ category.

If you would like a list of articles that are contained within two or more categories, there is an extension for that. For example, as in the example mentioned above, you can create this list by using the Dynamic Page extension. The syntax for the above example is below. See the DPL Manual for additional syntax help

Using This Syntax:
<DPL>
 category = H264
 category = DSP-BIOS
 category = 64x+
 columns = 4
</DPL>

Subcategories

Only add subcategories if they are truly a subcategory of the parent category. For example, Code Composer Studio v4 would be an appropriate subcategory of Code Composer Studio, as all versions of CCSv4 are also versions of CCS. An example of an invalid category relationship would be making "McBSP" a subcategory of "C6000 Peripherals". Even though the McBSP is a C6000 Peripheral, not all McBSPs are. A true child/parent relationship must hold in every case for the subcategory relationship to be valid.

Guidelines for adding content

• Search/browse to make sure a similar article does not already exist. If so, please improve the existing rather than create a "competing" article.
• Pages should be as easy and clear as possible. This can be achieved by some easy rules:
  1. On top of a (new) page give some introduction what's the page about, and in which context the content may be useful. It is always helpful to start with something the reader may already know. For example, a page about LED usage on EVMs may explain that an embedded system has no display and therefore controlling some LEDs can be helpful for debugging and status output.
  2. Avoid explaining all possible options if there is one golden way and the other options will be more painful, but the result will be the same. Or, if you want to explain all options (to be complete, or for the experts), mark and name them as option x only for experts.
  3. If there are options intended for everybody, shortly explain in which context each option might be the correct or best one to choose and what are the advantages/disadvantages of each option. For example: You can download the Linux kernel from TI/MontaVista (MV) or instead you can get the open source git kernel. Take MV one if ... and git one if ... and these are the advantages/disadvantages...
• Remove any proprietary/confidential content.
• Use the Show Preview button before using the Save Page button.
• Give the topic a specific name e.g. don't call a topic 'FAQs' - instead put the name of the product in the topic title somewhere. This is especially important with direct URL access - our mediawiki uses a flat namespace i.e. ?title=sometopic means that there can be only 1 'sometopic'.
• Avoid repeating information that is found on other wiki pages. This bad practice can create inconsistencies between pages and is difficult to maintain. Users of the wiki don't know which to believe.
• Avoid repeating info within a wiki page. It is better to list the common elements and differences than to repeat the same info multiple times with slight differences.

Guidelines for adding attachments

The key point to note is that Mediawiki has a flat namespace for all Media & Image content i.e. you cant have 2 files named stuff.pdf or image1.jpg. Hence, please name your attachments reasonably e.g. cg_xml_v2_12_layout.jpg not 1.jpg. If you try to upload a file with the same name Mediawiki will warn you: -

A file with this name exists already, please check Image:Release 610 overview public.pdf if you are not sure if you want to change it.

You can then choose to rename your destination filename or overwrite the original if it makes sense, i.e. if you are updating a file.

Syntax Guidelines

General Syntax Recommendations

In all cases where possible, try to use wiki markup, rather than HTML markup.

Examples

• Use the wiki list delimiters (*/#) for making unordered and ordered lists. Don't use HTML markup for lists. Avoid any of the following html tags <ul>, </ul>, <ol>, </ol>, <li>, </li>. One of the reasons for the popularity of mediawiki is the fact that users don't have to know the ins and outs of HTML. Using wiki markup will make it easier for others to add/modify your content in the future.
• Use mediawiki tables, rather than HTML tables. For similar reasons as above. Tables are complicated enough as they are.

Links to Other Embedded Processors Wiki Articles

Links to other articles from within the wiki are encouraged, as it provides users a pathway to content that they might be searching for. However, the best practice is to use Internal Mediawiki links, rather than hard URL links.

Benefits of "internal links" instead of "hard links"

• If you download a local/offline version of the wiki then the internal links will properly link to other offline pages while hard links will attempt to go over the internet.
• Allows you to 'back traverse' the wiki. That is, if you go to a page with soft-links you can click the 'What links here' link in the toolbox on the left and you can see the soft sublinks. If you use the hard links you lose that ability.
• If you misspelled the internal link then Mediawiki automatically colors the link red to alert you that the page doesn't exist. For example, here is an invalid link and here is a valid link.
• If the domain ever changed (no plans to do so) then the links would not need to be updated.

Examples of Internal Link (Soft Link - PREFERRED)
[[Main_Page]] looks like: Main_Page.
[[Main_Page|My text]] looks like: My text.
[[Main Page]] looks like: Main Page (i.e. underscores can be entered as spaces).
[[:Category:Codec Engine|Codec Engine]] looks like Codec Engine.

External Link (Hard link - NOT RECOMMENDED FOR LINKING TO OTHER WIKI PAGES)
[http://www.ti.com TI.com] looks like: TI.com.

Links to TI literature/documents

If linking to a TI doc (spruXXX, spraXXX, sprsXXX, etc), you can use the "tidoc" InterWiki link. For example, to link to spru360, use [[tidoc:spru360]] (appears as tidoc:spru360) or [[tidoc:spru360|spru360]] (appears as spru360).

• Note: you should NOT add the version of the doc (typically a trailing letter) to the link. For example, spru360 is currently at version 'e'. The InterWiki link will take you to the latest rev of the doc. It should not be part of the link.

Often times a document will have a corresponding zip file. For example, the app note spraa46 Advanced Linker Techniques has a zip file with code examples. To write a link for those code examples you would write something like [[tizip:spraa46]] (appears as tizip:spraa46) or [[tizip:spraa46|code examples]] (appears as code examples).

Links to TI Product Folders

If linking to a TI product folder you can use the "tifolder" link. For example, to link to the OPA333 product folder use [[tifolder:opa333]] (appears as tifolder:opa333) or [[tifolder:opa333|OPA333]] (appears as OPA333).

Renaming articles

If you make an article and later don't like the title of it then you can't delete it unless you have SysOp permissions.

However you can easily rename it. To do so, just click Move from the drop down arrow on the top.

Creating new device family articles

Links from the Main_Page need to point to solid content hence there are some rules regarding links to new device families from the Embedded Processors Device Table. Typically this initial work would be done by TIers. The community might then contribute articles to this new Category.

1. Content - the Apps/Engineering teams need to create sufficient content to attain a link from the Main Page - 10+ articles is a good start.
2. Fleshed out category page - edit the actual category page to give a nice intro to the product line so that customers get a quick datadump on what it is. Good examples are Category:OMAP35x or Category:C5000 i.e. an intro blurb and then the automated index of pages marked with that device family category
3. Overlapping content - check similar device families for articles which may apply to this new device family e.g. many OMAP35x articles also aply to AM35x hence should additionally be tagged with the latter catgeory (this is also why we recommend that categories be broad i.e. narrow categories equals more rework!

Leave a Comment