Register (free!) to see more.
What is OpenID?
Contents Registered members can join this collaboration or post a comment.
Return to the list of Key Collaborations.
Table of contents
Return to the list of Key Collaborations.
How Deep ARE Those Depths, Anyway?
So let's just recap the things I have to figure out:
- I don't know much XML terminology. Am I working in XML, or working in DITA with XML, or programming in XML, or what?
- I don't know how to structure XML documents, or how to make a documentation plan for a project that will use XML.
- I don't know what the options are, or whether XML is right for this project.
- I don't know the best resources for beginning XML people - everything I've read seems to assume that you already know all about tagging and style sheets and content management.
- I don't know how I can be such a good tech writer and still not know any of that stuff!
- I don't know why I put XML on my resume just because I bought a book about it once and meant to read it but never got around to it.
- I don't know how long this list is going to be by the time I'm done this project!
First Things First
First order of business - Find Resources. I need rudimentary resources on the following:
- XML terminology
- Determining whether XML is right for a project
Concurrently, I will develop project requirements for the Knowledge Base, because I read Ann Rackley's excellent "Don't Lead With Technology" article and took it to heart.
I was very pleased to find The W3Schools XML Tutorial, which looks like it will be a pretty good basic tutorial on XML. You gotta love a tutorial that starts with "XML stands for Extensible Markup Language." That's right where I need to be!
On a related note, the link in the above paragraph might be my first XML link! I copied it from the TOC, but it works and it makes me happy. I'm clearly way, way too easy on myself!
Getting Through The Tutorial, and Learning What's _Not_ XML
The W3 tutorial is doing a pretty good job of explaining what XML is and does. I haven't yet found a justification for their statement that you need a good understanding of Java, etc to understand it.
One of the first statements they make is that you have to define your own tags. I certainly hope they're planning on saying how to do that. Not to mention how to use them - I had no idea how to get the "Getting Through The Tutorial" heading into the regular Heading 2 font and size, because it looks in the sample like you have to start both with a single exclamation point, which doesn't really make sense. So I used the two exclamation points instead. Come to think of it, I'm not even sure that Wiki syntax is XML - in fact, from what I learned this morning it probably isn't. So I've been a little confused between all the new things I'm learning. It's all good though! Knowledge is power! (And why don't those exclamation points do anything? Inquiring minds want to know! As the Almighty Queen of the Extraneous Exclamation Point, this is going to have a lot of relevance for me.)
Possibly I digress.
Something that made me a little nervous was this idea of writing a program to interpret the XML. I'm not a programmer. I'll cross that bridge when I come to it.
The first part of the tutorial deals with the uses and purpose of XML. Not on any kind of project level, just the idea that it's different from HTML because HTML is concerned about how information looks, and XML is concerned with describing information. There's more, but that's the gist.
The next part of the tutorial deals with the rules of XML. These are quite simple and actually somewhat of a relief to a completely anal person like myself. In fact, I have a little bit of a head start, because HTML tags in different cases, tags with no closing tag, etc - that stuff drives me batshit.
The things I'm way out in front of the pack on are:
- closing tags are required
- all tags are case sensitive
- tags must be properly nested
The things that I understand and will get used to quickly are:
- root element must be defined
- attribute values must be quoted
- white space is preserved
- there's a comment format
A small thing I don't think I realize the significance of is:
- CR/LF is always stored as LF - I can't figure out if I care about this, but I guess I'll find out.
So I'm feeling somewhat confident that at least I'll be able to figure out how to put the information together. There's still a niggling little worry about defining my own tags and writing a program that reads them.
Project Requirements
I promised some project requirements for the Knowledge Base. I'm trying to be careful not to write the requirements on purpose so that they point to XML just because I want to use it. (So it's probably a plus that I'm essentially clueless about the capabilities of XML.) Who can resist new technology? So in no particular order, what I know I want is:
- search functionality that will retrieve both documents and pieces of documents depending on how the keywords for each piece are defined
- a repository for both individual procedures (some of which are already written and some aren't) and user manuals that are already written
- users should be able to use the information online or print it with equal success, the printed docs should look like our online docs & vice versa
- a user interface where people could enter procedures that will be checked by a content specialist and added to the KB, but it would be great if the tags & stuff could be added automatically
- people need to be able to find documents in groups and individually, so users can search on and print stuff like "Circulation Accounting Procedures" and "General Ledger Policies" as well as individual procedures like "Posting a Journal Entry."
I'm sure there will be more.
{SUBMIT()}{SUBMIT}
