Sean,
I think you may be asking questions with no solid answers. There are likely a sizable variety of opinions out there, all of which are just that... opinions. The short answer is that you have to figure out what works for you, and this may not be what works for someone else.
There are some that would tell you to forget this whole exercise and just use an existing data structure, like DITA or Docbook. This is certainly an option. I do not use either because neither works for me.
So, let me tell you what does work for me, in reference to the questions you asked. This is all subjective in your case, but it is based on a well-used and highly-refined workflow, producing good results for many years.
1 - Element name conventions - I like the lower-case element names that DITA uses, like <p>, <fig>, <ol>, etc. because 1) They are short and easy to visualize 2) I know what they mean because I'm an author and they also look like HTML in some cases 3) The shorter the element tag, the less overhead in the structured file and also XML, if you export to XML.
2 - As an author, I find it much quicker to specify an explicit <ol> or <ul> element, rather than set an attribute. Furthermore, it is much easier to visualize in the structure view. Furthermore, it is less overhead in the source file. DITA calls a heading element <title>... I like that better than <Head>, but again, that's just me.
3 - For figures, I use a <fig> element which maps to my "AnchorGraphics" tag. The <fig> element has two children... <image> and <title>. The <image> element is a graphic element that inserts an anchored frame into the empty AnchorGraphics paragraph (created by <fig>). Then, the container <title> element inserts a new paragraph for the figure caption. The end result is the same as standard unstructured FM usage, except that the management of the AnchorGraphics placeholder is much better automated and controlled. IOW, you don't have to worry about it anymore... the element structure does it for you. One of the myriad of benefits of structure.
4 - DITA defines a single <note> element which has an attribute to control whether it appears as a note, caution, etc. I like this approach. You could reuse the <para> element but my thought is that this would really complicate your formatting context rules. The explicit <note> element seems much better.
5 - Tables - Yes to your basic question, although there are plenty of different names you could choose for the elements. To comply with the CALS or DITA model, you would also need one more ancestor in the tree that is the parent to the actual table element. In DITA, this is the <table> element, and the actual table element is a <tgroup> element as a child. In my EDD, the <table> element works very much like the <fig> element, inserting an empty paragraph into which the child <tgroup> element inserts the actual table. This models typical unstructured usage and works very well for me.
Throughout all of this, you'll note that I reference DITA a lot, but claim that I don't use DITA. I really like the DITA structure definition (the <topic> DTD mainly)... I find it very intuitive and well-designed for general authoring. However, I find little use for other DITA things, like its focus on topic-oriented content management and a huge swath of other complexities that are just a nuisance if you don't need them. So, I effectively have my own EDD, but the underlying structure definition is mostly ripped off from DITA. I'd encourage you to at least look at the DITA spec and see how they did it. The simplest way would be to use the FM menus to create a sample DITA topic and mess around with it.
I hope this helps.
Russ
AdChoices