How to Create a Video Sitemap with WordPress

Google VideosIf you have a lot of video content on the web, you will want to create a video sitemap to submit to Google and the other search engines.  Here is a step-by-step tutorial on how to create a video sitemap with WordPress.

Some of these steps might not be appropriate for your situation, but I will start at the point where you have your video files (e.g. .M4V, .MP4, .MOV, .FLV, etc…) on a publicly-accessible  web server somewhere and you have a fresh empty installation of WordPress also on a publicly-accessible  web server.

Publish Video Posts

  1. Create a new post category and give it the name “video.”
  2. Create a new post, and add a custom field called “video_url.” This can either be done on a post-by-post basis or you can use a plugin to automatically create custom field forms such as Custom Field Template.
  3. Give the custom field the full URL value of your first video URL (e.g.
  4. Give the post the title of the video.
  5. If you have a transcript or some written content about the video write it in the WYSIWYG editor. This will be seen by anyone who visits your site and will be good for SEO purposes.
  6. Write a short description of the video in the Excerpt text box. DO NOT add any code or any character other than alphanumeric characters.
  7. If your theme allows for a featured image, add the featured image in that section.  If not, you might choose to create another custom field and add the full URL value of the image location. It is recommended to make this image the same width and height of the video.
  8. Add relevant tags in the Post Tags section.
  9. Publish
  10. Repeat until all of your videos each have a unique post.

 Create Custom XML Page

  1. In your theme directory where your index.php and style.css files exist, create a new file and call it video-sitemap.xml.
  2. Copy this code, and only this code, into video-sitemap.xml:
<!-- create a Video Sitemap template -->
Template Name: Video Sitemap

<!-- create a variable called $posts which is the contents of all of your video posts -->
$posts = query_posts(array_merge(
'cat' => 'video',
'posts_per_page' => 9999,
'meta_key' => 'video_url'

<!-- this is the namespace of the XML file and the top of the file you will be producing -->
echo '<urlset xmlns=""
<!-- loop to get each video and thumbnail URL, one at a time -->
<?php foreach ($posts as $post) {
$hosted_file_name = get_post_meta($post->ID, 'video_url', true);
if ( has_post_thumbnail() ) {
$videothumbnail = get_post_thumbnail ($post->ID);
<!-- get video URL as its own element node along with the video attributes, and you must change the dummy URLs -->
<loc><?php echo the_permalink($post->ID); ?></loc>
<video:thumbnail_loc><?php echo $videothumbnail ?></video:thumbnail_loc>
<video:title><?php the_title(); ?></video:title>
<video:description><?php the_excerpt(); ?></video:description>
<video:content_loc><?php echo $hosted_file_name; ?></video:content_loc>
<video:publication_date><?php echo get_the_date('Y-m-d'); ?></video:publication_date>
<video:category>Here write the main content category of all of your videos</video:category>
$posttags = get_the_tags();
if ($posttags) {
foreach($posttags as $tag) {
echo '<video:tag>' . $tag->name . '</video:tag> ';
<!-- this should be set to "no" if these are not suitable for kids -->

<?php } ?>

  1. Save this file and uploaded it to the server
  2. Return to your WordPress dashboard and create a new page. Give it the title “Video Sitemap” so that the URL is
  3. You will find a “Page Template” dropdown box. Choose “Video Sitemap” (which was declared at the top of the XML file you just created).
  4. Publish

There should now be a video sitemap at You can submit this URL to Google Webmaster Tools as a sitemap.

Digitally Displaying Math Formulas with MathML

MathML 3.0In an earlier post I gave a primer on MusicXML as a way to create XML sheet music. Another way that XML can be used to structure and display specialized character types is MathML. One of the challenges of displaying mathematical formulas is that there are many different line heights, superscripts, subscripts, positions of fractions and special characters. Recently adopted by EPUB 3, MathML is a format first recommended by the WC3 in 1998 with version 3.0 finalized in 2010.

Presentation MathML vs. Content MathML

There are two different types of MathML:

  1. Presentation MathML
  2. Content MathML

Sometimes called P-MathML, Presentation MathML is used when the presentation of mathematical expressions, perhaps in the case of printing the formulas in a textbook.  Content MathML, sometimes know as C-MathML, is better used when the functionality of the formula is needed within the XML to perform a task. C-MathML keeps the semantics of the formula.

Here is the code used to write the quadratic equation*:

<math mode="display" xmlns="">
<mo form="prefix">−</mo>

MathML is better than using .gif images of formulas, because MathML is searchable whereas the content of a .gif is not. Notice how the following code is selectable with your mouse, meaning they are actual values read by your computer: (NOTE: Only displays correctly in Safari or Firefox who have been the first to adopt MathML natively in the browser


The +/- found in the above quadratic equation must be written in P-MathML because it is not an actual operator but a theoretical concept. If you were to write the quadratic formula in C-MathML you would have to write out two separate equations.

WordPress Codex Rocks!

WordPressIt was recently announced that 15% of all websites around the world run on WordPress. This website is one of them.  It’s a really great platform and its success can be attributed to many factors. It’s free, it is simple to use, it has a huge community of users and it has great documentation in the WordPress Codex.

The fact that it is free gets people in the door. That’s the removal of major barrier to entry—you just learn a thing or two about LAMP servers and PHP and you have a website.  I often get asked how WordPress can be free, and although I don’t have the exact answer I direct people to the website of the company, Automattic, who builds it.  The company does offer VIP services to paying clients and probably has a solid base of investors.

But just because something is free doesn’t mean people are going to continue to do it. Take jogging, for example.

WordPress is simple to use and has a large community in large part due to its documentation. 

I am in awe of the thought and care put into this software. It does so many things well: it is customizable in the way it looks (themes) and what it can do (plugins), and the development team has built intuitive functions that turn PHP into everyday English.  It is very easy to use.  But it would be a million times harder to use if the Codex were not in place and maintained on a regular basis.  I would dare to say that if the WordPress documentation contained in the Codex were not there that most people would have never heard of WordPress, at least not as quickly as they have.  I know that I have been on the verge of frustration many times but was satisfied by the documented tutorials and information that are readily available (and accurate) for free on

There is a very strong developer community too.  The forums on are very active, and of the thousands of questions you will find on the site you might find only one or two answered by malcontents; it’s a friendly bunch.  There are community educational events called WordCamp held all over the world.  I attended one in Birmingham, Alabama last year, and not only did I learn some advanced programming skills I also made some good friends.

My point is this: No one would go to WordCamp or continue to use WordPress if they couldn’t learn it easily, accurately, and on their own time.  If the Codex were not there online for me to reference every time I needed it, this website might have been made by some clunky Microsoft product, but thankfully it doesn’t have to be.

Documentation is the key to success.  Winners have it, and losers don’t.

Louisiana Digital Interactive Media and Software Tax Credit

Here is an important law in Louisiana pertaining to tax credits given to digital media production. Like most laws it is a blob of visually unorganized and hard to read words. This is an easier way to read it. (italics and underlined text and links are not part of the original document).

§6022. Digital interactive media and software tax credit


    • This Section shall be known and may be referred to as the “Louisiana Digital Media and Software Act”.
    • The primary objective of this Section is to encourage development in Louisiana of a strong capital base for the production of digital interactive media products and platforms in order to achieve a more independent, self-supporting industry. This objective is divided into immediate and long-term objectives as follows:
        • (a) Attract private investment for the production of digital interactive media products and platforms in this state.
        • (b) Develop a tax infrastructure which encourages private investment. This infrastructure will provide for state participation in the form of tax credits to encourage investment in state-certified productions.
        • (c) Develop a tax infrastructure utilizing tax credits which encourage investments in multiple state-certified productions.
      • (2) Long-term objectives are to:
        • (a) Encourage increased employment opportunities within this sector and increased competition with other states in fully developing economic development options within digital interactive media products and platforms.
        • (b) Encourage new education curricula in order to provide a labor force trained in all aspects of digital interactive media.
        • (c) Encourage partnerships between digital interactive media developers and Louisiana educational institutions.


  • For the purposes of this Section:
    • (1) “Base investment” means the actual funds expended in Louisiana by a state-certified production as production-related costs for design or development of digital interactive media, including costs for payroll and component parts, as defined in this Section.
    • (2) “Component parts”, with respect to digital interactive media, means all elements that are integral to the functioning or development of such products and platforms. Some examples of “component parts” are software, computer code, image files, music files, audio files, video files, scripts and plays, concept mock-ups, software tools, and testing procedures. Component parts shall also include, but not be limited to computer servers, workstations, server racks, hard drives, optical drives, monitors, keyboards, integrated video and audio equipment, networking routers, switches, network cabling, and any other computer-related hardware necessary to create or operate a digital interactive media product or platform.
    • (3) “Department” means the Louisiana Department of Economic Development.
    • (4)
      • (a) “Digital interactive media” means products or platforms that are intended for commercial production, use, or distribution; that contain at least two of the following types of data: text, sound, fixed images, animated images, video, or 3D geometry; and that have all of the following three characteristics:
        • (i) “Digital” means a system that uses discrete (discontinuous) values ordinarily symbolized numerically to represent information for input, processing, transmission, and storage. A digital system would be contrasted with an “analog” system which uses a continuous range of values to represent information. The term “digital” includes, but is not limited to information input, processed, transmitted and stored via the Internet.
        • (ii) “Interactive” means a digital media system for inputting, processing, transmitting, or storing information or data in which users of the system are able to respond to the digital media system by inputting, transmitting, processing, or storing information or data in response to the information or data provided to them through the digital media system. “Digital media system” means communications delivered via electronic energy where the information stored, transmitted, or received is in digital form.
        • (iii) “Media” means communication tools used to store, transmit, distribute, and deliver information and data. The term “media” includes methods and mechanisms for information distribution through, but not limited to distributed networks, such as the Internet, and through compact disc, CD-ROM, various types of DVD, and other removable storage drives and devices.
      • (b) Some examples of digital interactive media are:
        • (i) Video or interactive games.
        • (ii) Simulation software.
        • (iii) Interactive educational or training products.
        • (iv) Internet sites designed and developed as social media.
        • (v) Software applications that provide connectivity and communications between mobile devices and digital interactive media web platforms.
        • (vi) Technology designed to stream live or pre-recorded video content over the Internet to large simultaneous audiences.
      • (c) “Digital interactive media” shall not include:
        • (i) Software development designed and developed primarily for internal or operational purposes of the company.
        • (ii) Largely static Internet sites designed to provide information about a person, business, company, or firm.
        • (iii) Products regulated under the Louisiana Gaming Control Law.
    • (5) “Company” means an entity authorized to do business in the state of Louisiana and engaged in the business of producing digital interactive media as defined in this Section. “Company” shall not mean or include any company owned, affiliated, or controlled, in whole or in part, by any company or person subject to any of the following:
      • (a) Has a contract or application with the Department of Economic Development that is in default or noncompliance.
      • (b) Is in default on a loan made by the state or a loan guaranteed by the state.
      • (c) Has ever declared bankruptcy under which an obligation of the company or person to pay or repay public funds or monies was discharged as a part of such bankruptcy.
    • (6) “Expended in Louisiana” means an expenditure to lease immovable property located within the state; an expenditure as compensation for services performed in the state; or an expenditure to purchase or lease tangible personal property within the state where the transaction is subject to the state sales or lease tax provisions of Title 47 of the Louisiana Revised Statutes of 1950. A transaction that is subject to the state sales or lease tax provisions of Title 47 of the Louisiana Revised Statutes of 1950 shall include transactions which are also subject to a statutory exclusion or exemption.
    • (7) “Office” means the office of entertainment industry development in the Department of Economic Development as provided in R.S. 51:938.1.
    • (8) “Payroll” includes all salary, wages, and other compensation sourced or apportioned to Louisiana, including related benefits.
    • (9) “Person” means a natural person, corporation, partnership, limited partnership, limited liability company, joint venture, trust, estate, or association.
    • (10)
      • (a) “Production expenses” means preproduction and production expenditures in the state directly relating to a state-certified production including without limitation the following: testing software, source code development, patches, updates, sprites, three-dimensional models, and level design; costs associated with photography and sound synchronization, lighting and related services; rental of Louisiana facilities and equipment; purchase of prepackaged audio files, video files, photographic, or libraries; purchase of licenses to use pre-recorded audio files, video, or photographic files; development costs associated with producing audio files and video files to be used in the production of the end product under development.
      • (b) “Production expenses” shall not include any of the following:
        • (i) Expenditures for or related to marketing, promotion and distribution.
        • (ii) Administrative, payroll, and management services which are not directly related to management of the state-certified production.
        • (iii) Food, entertainment, and lodging expenses.
        • (iv) Amounts that are later reimbursed by the state.
        • (v) Costs related to the transfer of tax credits.
        • (vi) Amounts that are paid to persons or entities as a result of their participation in profits from the exploitation of the production.
        • (vii) Any application fee, or state or local taxes.
  • (11) “Resident” or “resident of Louisiana” means a natural person and, for the purpose of determining eligibility for the tax incentives provided by this Section, any person domiciled in the state of Louisiana and any other person who maintains a permanent place of abode within the state and spends in the aggregate more than six months of each year within the state.
  • (12) “Secretary” means the secretary of the Louisiana Department of Economic Development.
  • (13) “State-certified production” shall mean a digital interactive media production or a component part thereof approved by the office.
  • (14) “Tax credit” means the digital interactive media and software development tax credit authorized by this Section.
      • (1) For applications for state-certified productions submitted to the office prior to July 1, 2009, and subsequently approved by the office and secretary, there is hereby authorized a tax credit against state income tax which shall be earned by producers at the time funds are expended in Louisiana on a state-certified production as follows:
        • (a) For each of the first and second years following certification of the project as a state-certified production, the producer shall earn tax credits at the rate of twenty percent of the base investment for that year.
        • (b) For each of the third and fourth years following certification of the project as a state-certified production, the producer shall earn tax credits at the rate of fifteen percent of the base investment for that year.
        • (c) For each of the fifth and sixth years following certification of the project as a state-certified production, the producer shall earn tax credits at the rate of ten percent of the base investment for that year.
        • (d) No tax credits may be earned under this Section after the sixth year following the certification of the project as a state-certified production.
        • (2) For applications for state-certified productions submitted to the office on or after July 1, 2009, and subsequently approved by the office and secretary, there are hereby authorized tax credits which shall be earned by a company at the time funds are expended in Louisiana on a state-certified production as follows:
          • (a) Credits shall be earned at the rate of twenty-five percent of the base investment.
          • (b) To the extent that base investment is expended on payroll for Louisiana residents employed in connection with a state-certified production, additional tax credits shall be earned at the rate of ten percent of the payroll.


        • (1) For tax credits earned for expenditures made on or before December 31, 2011:
        • (a) The credit shall be allowed against the income or franchise tax due from a taxpayer for the taxable period in which the credit is earned as well as the immediately preceding period. If the tax credit allowed pursuant to this Section exceeds the amount of such taxes due from a taxpayer, then any unused credit may be carried forward by the taxpayer as a credit against subsequent tax liability for a period not to exceed ten years. However, in no event shall the amount of the tax credit applied by a taxpayer in a taxable period exceed the amount of such taxes due from the taxpayer for that taxable period.
        • (b) All entities taxed as corporations for Louisiana income tax purposes shall claim any credit on their corporation income and franchise tax return.
        • (c) Individuals, estates, and trusts shall claim their share of any credit on their income tax return.
        • (d) Entities not taxed as corporations shall claim their share of any credit on the returns of the partners or members as follows:
          • (i) Corporate partners or members shall claim their share of any credit on their corporation income tax returns.
          • (ii) Individual partners or members shall claim their share of any credit on their individual income tax returns.
          • (iii) Partners or members that are estates or trusts shall claim their share of any credit on their fiduciary income tax returns.
        • (e) Any tax credits allocated to a person and not previously claimed by any taxpayer against his Louisiana state income or franchise tax may be transferred or sold by such person to another person, subject to the following conditions:
          • (i) A single transfer or sale may involve one or more transferees. The transferee of the tax credits may transfer or sell such tax credits subject to the conditions of this Section.
          • (ii) Transferors and transferees shall submit to the office and Department of Revenue in writing, a notification of any transfer or sale of tax credits within thirty days after the transfer or sale of such tax credits. The notification shall include the transferor’s tax credit balance prior to transfer, the state-certified production number, the name of the state-certified production, the transferor’s remaining tax credit balance after transfer, all tax identification numbers for both transferor and transferee, the date of transfer, the amount transferred, a copy of the tax credit certificate, and any other information required by the office or the Department of Revenue.
          • (iii) Failure to comply with this Paragraph will result in the disallowance of the tax credit until the taxpayers are in full compliance.
          • (iv) The transfer or sale of this credit does not extend the time in which the credit can be used. The carryforward period for credit that is transferred or sold begins on the date on which the credit was originally earned.
          • (v) The transferee shall apply such credits in the same manner and against the same taxes as the taxpayer originally awarded the credit.
      • (2) For tax credits earned for expenditures made on or after January 1, 2012:
        • (a) The tax credits shall be refundable and allowed against the individual or corporate income tax liability of the companies or financiers of the project in accordance with their share of the credit as provided for in the application for certification for the project. The credit shall be allowed for the taxable period in which expenditures eligible for a credit are expended as set forth in the final tax credit certification letter. Any excess of the credit over the income tax liability against which the credit may be applied shall constitute an overpayment, as defined in R.S. 47:1621(A), and the secretary of the Department of Revenue shall make a refund of such overpayment from the current collections of the taxes imposed by Chapter 1 of Subtitle II of this Title, as amended. The right to a refund of any such overpayment shall not be subject to the requirements of R.S. 47:1621(B).
        • (b) At the time of final certification of tax credits, a company may elect, on a one-time basis, to receive a rebate of the credits. The amount of the rebate shall be eighty-five percent of the face value of the credits. Upon receipt of the final tax credit certification letter and any necessary additional information, the secretary of the Department of Revenue shall make payment to the company, or its irrevocable designee, which may include but not be limited to a bank or other lender, in the amount to which he is entitled from the current collections of the taxes collected pursuant to Chapter 1 of Subtitle II of this Title, as amended.


        • (1) The office may promulgate rules in accordance with the Administrative Procedure Act to establish the policies and program elements regarding project qualifications of state-certified productions and any other matter necessary to carry out the intent and purposes of this Section. Such rules shall be subject to oversight by the House Committee on Ways and Means and the Senate Committee on Revenue and Fiscal Affairs.
        • (2) Application. A company seeking to participate in the tax credit program shall apply to the department through an application process established by the department.
        • (3) Certification.
          • (a) The office shall review the company’s application and any other information which it deems appropriate for determination of the project’s eligibility for initial certification. For a project deemed eligible, the office shall provide an initial certification of the project as a state-certified production to the company and to the secretary of the Department of Revenue. The initial certification shall be effective for expenditures made no more than six months prior to the date of initial certification and shall be valid until the project is completed. The initial certification shall include a unique identifying number for each state-certified production.
          • (b) Prior to final certification of tax credits of a state-certified production or any portion thereof, the company shall submit to the office a cost report of production expenditures. The cost report of expenditures shall be subject to an agreed-upon procedures engagement conducted by a certified public accountant in accordance with statements on standards for attestation engagements established by the American Institute of Certified Public Accountants. The accountant shall issue a report in the form of procedures and findings. The accountant shall be a certified public accountant licensed in the state of Louisiana and shall be an independent third party unrelated to the company. The agreed-upon procedures shall be established by the office and secretary, with assistance from the Society of Louisiana Certified Public Accountants. The department may request additional audits of the project expenditures, the cost of which shall be borne by the company.
          • (c) Upon completion of all or a portion of a state-certified production, the office shall review the production expenses and, if approved by the office and secretary, issue a final tax credit certification letter to the company. The certification letter shall include the identifying number assigned to that state-certified production in the initial certification.
          • (d) As a condition for receiving certification of tax credits under this Section, state-certified productions may be required to display the state brand or logo, or both, as prescribed by the secretary.


      • If the office finds that funds for which a company received credits according to this Section are not actually expended in Louisiana as a production-related cost of a state-certified production, then the company’s state income tax for such taxable period shall be increased by such amount necessary for the recapture of credit provided by this Section.


        • (1) Credits previously granted to a taxpayer, but later disallowed, may be recovered by the secretary of the Department of Revenue through any collection remedy authorized by R.S. 47:1561 and initiated within three years from December thirty-first of the year in which the credits were earned.
        • (2) The only interest that may be assessed and collected on recovered credits is interest at a rate of three percentage points above the rate provided in R.S. 9:3500(B)(1), which shall be computed from the original due date of the return on which the credit was taken.
        • (3) The provisions of this Subsection are in addition to and shall not limit the authority of the secretary of the Department of Revenue to assess or to collect under any other provision of law.


      • The provisions of this Section shall not apply to any investments or expenditures that qualify for tax credits under R.S. 47:6007.


      • J. A taxpayer shall not receive any other incentive administered by the Department of Economic Development for any expenditures for which the taxpayer has received a tax credit or tax rebate under this Section.


      • K. Repealed by Acts 2011, No. 415, §3, eff. July 11, 2011.




What is EPUB?

EPUBEPUB is a formatting standard for publishing ebooks like those you can find on Apple iBooks, Google Books and many other online sources of electronic books. This standard was set by the International Digital Publishing Forum (IDPF).  This standard is open, which means anyone can learn it inside and out, and it is royalty-free, which means you don’t have to pay anyone to use it. Built into EPUB is a platform for digital rights management (DRM), which is a hot topic in any digital media including text, music and video.

The current version of EPUB, 2.0.1., uses as its data type definition (DTD) the DTBook standard established by the Daisy Consortium.

The basics of the EPUB standard look like this*:

<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "">
<html xmlns="" xml:lang="en">
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=utf-8" />
<title>Pride and Prejudice</title>
<link rel="stylesheet" href="css/main.css" type="text/css" />
</head> <body> ... 
</body> </html>

The EPUB package can contain text, audio, or a navigation control for XML (NCX) which is a file used to navigate to any section of the book. The main file in this package is an Open Packaging Format (OPF) file in which meta data such as title and language are stored.  This OPF file might have any number of other optional elements and attributes. A full list of OPF specifications can be found here. There are also recommendations being made for EPUB 3.o which takes HTML5 into account.


OpenDocument Format 1.2

OpenDocument Format )ODF logo)Technical writers should all know about OpenDocument Format (ODF).  A new version, ODF 1.2, has recently been approved by the Organization for the Advancement of Structured Information Standards (OASIS).  OpenDocument Format is an XML-based way to create office documents that are independent of any proprietary application or software platform.  Documents created in this format will not become obsolete if and when your organization tries out new software.  This version, ODF 1.2,  includes improvements and support for digital signatures, semantic web technology, and the OpenFormula spreadsheet language.

What Software Currently Works with OpenOffice Format?

Users of are already familiar with files created in ODF.  Here is a list of the OpenOffice file type extensions, which are all based on the ODF format:

  • ODT (text document)
  • ODS (spreadsheet)
  • ODP (presentation)
  • ODG (graphics)
  • ODF (math formulas)

These file types are merely ZIP folders.  You can unzip them and find open-source XML files to explore and examine.  When you unzip an ODT file, for example, the main file to look at is named manifest.xml and can be found in a folder named META-INF. The content.xml file holds the content of the document, the meta.xml file holds the meta data about the document, and the style.xml file defines how the style properties of how the content is laid out. The settings.xml file defines the preference settings of the document.

If you have OpenOffice installed on your computer, you can find the DTDs for OpenOffice are found in the software installation files in a subfolder BASIS >> SHARE >> DTD.

OpenDocument Format(ODF) has been adopted by the major players in I.T., including Google Docs, IBM, Microsoft Office, Nokia, WordPad,  and WordPerfect, among many others.  Making sure your organization’s documents are in this format is an important step to take to ensure a future that facilitates growth and interoperability with these companies.



Drawing Scalable Vector Graphics (SVG) with XML

bar graphWhen you see graphics on a website, you normally think that it was created by a camera or even perhaps a software tool like Adobe Illustrator. You might realize this in the back of your head but don’t think about it every day—that image is just a bunch of computer code that is being displayed as a visual image on your monitor.

Scalable Vector Graphics (SVG), also known casually as “vectors,” are graphics that can be rendered by drawing software or by writing code.

It’s simple to demonstrate in HTML. If you code this:

<svg xmlns="" version="1.1">
<circle cx="100" cy="50" r="40" stroke="black"
stroke-width="2" fill="red" />

You get this:

Or you can draw a line:

<svg xmlns="" version="1.1">
<line x1="0" y1="0" x2="200" y2="200"style="stroke:rgb(255,0,0);stroke-width:2"/>

So you can see that graphics can be delivered with code. This is useful if you are dealing with pie charts, line graphs, or bar graphs. As the numerical values of your data change, the graphical representaion can scale along with it.



The ROI of Good Documentation

Documentation is often the last priority in a business’s plan. Most number crunchers only think of the short term, and in the short term everyone in a company gets all of the internal memos about the motivation and details of a plan. It appears that you do not need permanent and clear documentation. So why spend money on the long-term?  What is the ROI of good documentation? After all, if a company does not succeed in the short term then there will not be a long term.

red binder among gray bindersDocumentation Isn’t Just About the Long Term

If your products or services are accompanied by instructions, guides, or tutorials then two things will happen:

  1. Your customers will invest happy and enjoyable time, right now,  into your product
  2. You won’t need as many customer support representatives, and you will save money on labor costs right now

If your company’s workflow and procedures are documented you will get higher productivity from less downtime due to misunderstandings and uncertainty.

Go Big or Go Home

If you are not planning for the future, though, you might as well quit now.  What are you going to do when the big sales start coming in—scramble around and try to not only hire new people but train them as well?  And all while trying to please the new customers?  Good luck with that. No, you need to have everything written down so that these sort of transitions happen seamlessly.

Say you are a software company with a great product that people are using and buying, and a larger company shows interest in buying you out for a large amount?  What are you going to give them, a bunch of code?  Not everyone can read code, and even if you have neatly commented out your code, most people in an organization do not want to sift thorough all of that.  You are going to have to present the prospective buyer with requirements and architecture documents for them to take you seriously.

Your Next Step

Hire a technical writer. Speak with someone who can learn your organization quickly and organize it in the terms that you think are most useful.  The technical writer does not have to have expertise in your field, only the abilities to listen, to categorize concepts and to present the information in every relevant media.  There might be an initial cost, but ROI of good documentation and the initial payoff are now and the potential earnings for your future are much greater.





XML Sheet Music

XML is not just used to organize text. It can be used as the framework to store scalable vector graphics (SVGs) and even sheet music.  Yes, xml sheet music.  This open file format known as MusicXML was developed by Recordare of Los Altos, California.

Because there are several approaches to conceptualize music, MusicXML has six different DTDs:

  • timewise.dtd (top-level element, time-based)
  • partwise.dtd (top-level element, based on the different parts of a score)
  • container.dtd
  • opus.dtd (connects multiple scores together into an opus)
  • midixml.dtd (represents a MIDI file)
  • sounds.dtd (defines whether or not a sound is solo or an ensemble)

There is a free download that contains all of these DTD files as well as several .XSD files and .XSL stylesheets. There are also .XSLT files that can be used to transform a score between the timewise and partwise DTDs.

This format has been developed quite well, and there are even ways to used XML to draw guitar tab and guitar chords as well as percussion notation. It is the hope of Recordare that HTML5 will be able to natively display the .MXL file type or at least will be a step in the right direction. Because .MXL files have to describe rhythm, pitch, time, harmony and sound, each individual measure of music can be a quite large chunk of code.  You can imagine how large a simple song file can be, not to mention a symphony. But XML is sturdy; if it conforms to the DTD it won’t break, and as a single document (as opposed to relational data) its performance and scalability is the right tool for the task.

It will be interesting to see how this technology is integrated into the lives of real, live, breathing musicians.  The possibilities are exciting to imagine.



Who Would Use DocBook?

DocBook duck

What is DocBook?

DocBook is a format.  It is a document format.  It is not the paper or the screen or the words. Instead it is a way to organize the words in a document.  DocBook is not the layout and styling of the text.  It is a way of labeling the different sections of the content by structure and semantics, sort of like using <h1> and <h2> but on steroids.

What’s good about it?

It makes the presentation of the written words available on every device and every technology. You only have to write it once, and it changes in all of the formats.  You can have a printed book along with an eBook along with the exact same information to send to any other device not yet invented.

Why use it?

Technical writers use it for some of the same reasons you use punctuation to differentiate between two concepts when they appear in the same sentence.  They also use it for the same reason you put paragraphs and chapters in books. DocBook is a way to group information that a computer can understand so that when other people want to find specific parts of your work they can. And though DocBook is not the way to style the text, it facilitates the universal formatting of different types of sections.

Who Uses DocBook?

The software industry uses it to write about their products and features.  It is also used in many other industries and hundreds of companies to construct their user manuals. It is used for enterprise-wide content organization and eBook publishers.

What Would You Not Use it For?

While DocBook is an excellent and widely-accepted way to organize concepts, it might not be the best choice for extremely large data sets which are more task-oriented.  If this is your main type of document, or if you have to include a lot of external references, or need it to integrate into on online help system, then maybe DITA is a better choice.