Template Self-Documentation Project
Table of contents
- 1. Status
- 2. Project Tree
- 3. Objectives
- 4. Background
- 5. How it works
- 5.1. The Template Format
- 5.1.1. The <div> wrapper
- 5.1.2. Summary table
- 5.1.3. Version History
- 5.1.4. Parameters
- 5.2. TemplateDoc() template
- 5.3. TemplateSummary() template
- 5.1. The Template Format
- 6. Other Approaches
- 6.1. Full Embedded Documentation
- 6.1.1. Description
- 6.1.2. Advantages
- 6.1.3. Disadvantages
- 6.2. Link to Documentation
- 6.2.1. Description
- 6.2.2. Advantages
- 6.2.3. Disadvantages
- 6.3. Hybrid Approach: Partial Embedded Documentation plus Link
- 6.3.1. Description
- 6.3.2. Advantages
- 6.3.3. Disadvantages
- 6.1. Full Embedded Documentation
- 7. Open Issues
- 8. Discussion
Status
This project is still underway as of March-2010. A few basic starter templates have been defined, but there is still refinement needed before this gets published.
Project Tree
Objectives
Primary
Define a mechanism to provide automatic documentation for the templates in a MindTouch installation.
Secondary
Said mechanism should:
- be very easy for users to deploy
- be very easy for Template authors to support
- be smart enough to understand whether a given template supports it, and handle it appropriately.
- where necessary, be linked back to the "official" documentation on the MindTouch wiki.
- include a template to generate a documented table of templates on a system (doc generator)
- work with existing MindTouch functionality
Background
Unlike extensions or scripts, templates have no built-in way to document themselves. As a result, for any given MindTouch installation, learning how to use the installed templates becomes a difficult task for the user, unless the admin has painstakingly managed the documentation for each one.
Now that templates are becoming a common form of app distribution via the App Catalog, this problem becomes more acute. Even if good documentation is provided on the App Catalog, it is not meaningfully linked to the actual template, so once the template is installed on a user's wiki it becomes completely disassociated from the documentation.
This project attempts to define a very simple way to embed sufficient metadata in a template to enable it to be self-documenting once installed on a user's wiki.
Note that the ability to export and import packages is not, in our opinion, a solution to this problem, since import/export mechanisms are not yet widely used nor reasonably accessible to users. The may change in the future, but for now we seek a different solution.
How it works
This solution satisfies all requirements. Here's how it works.
The Template Format
Of course, a template will be provided to document this format, and will be an easy way to create a new template. We'll call it "Template:templateTemplate" or something like that.
The <div> wrapper
At the top of each template is HTML that looks like this:
<div id="templateSelfDocumentation" if="false"> documentation goes here </div>
The id makes it easy to detect with Xpath. The if="false" means that it will show up both while editing and viewing the template page, but when you actually instantiate the template from another page, the complete <div> will be omitted.
Now, we're free to put human-friendly HTML-formatted documentation directly in the template!
Summary table
First is a table with basic summary information, tagged with a class="summary". Info includes:
- URL of the documentation page. This will make it easy for users to find the documentation after they have installed the template on their system
- Description - the basic description of the template. This is what would normally go in the first section of the documentation page.
- Requirements - What is needed to run the template, if anything (e.g., MindTouch version, UNSAFECONTENT, etc.)
Version History
Next is a table of version history, tagged with class="version". Versions are listed with the most recent at the top.
Parameters
Finally is a table of Template Parameters, tagged with class="parameters". This is only the first-level description; some templates (like TSTable()) might have additional tables breaking down each parameter, but these are not included here.
TemplateDoc() template
This is designed to work much like the ScriptDoc() template, for templates. By simply calling it with the name of the template, you have the start of a fine documentation page. Additional detail may be added, of course, including (especially) working examples, which by definition cannot be embedded in the template itself.
The first bits of this template are under construction here.
TemplateSummary() template
This template, just barely under construction here, generates a summary page of all templates installed on a system, along with version number, description, and link to the official documentation. Additional cool stuff is possible, like checking the installed version against the "official" one, etc.
This will only be useful if many of the templates support this format. We can only do what we can do! Possibly, only self-documented templates will be listed here, but we'll have to work on that.
Other Approaches
Following are other possible approaches to solving this problem. These approaches were all rejected for being greatly inferior to the selected approach.
Full Embedded Documentation
Description
Complete template documentation is embedded into the template itself, using a defined format and/or markup language, a la Perl POD.
In theory, this could be the best solution, but in practice there are some significant hurdles.
Advantages
- Entire template is fully portable
- No issues keeping doc page and template in sync
Disadvantages
- Hard to enforce standard
- Could be hard to support WYSIWYG documentation editing (probably requires entering docs with a mark-up language_. Can this be avoided?
- Template page itself cannot have working examples; would need a separate documentation viewer for that
- Templates can become bloated with documentation
Link to Documentation
Description
Inside each template, embed an easy-to-find link to the official documentation page on the MindTouch wiki (or wherever it is.) Documentation pages will have additional standard formatting enabling the "doc generator" to extract key details.
Advantages
- Only one very simple line of code needs to be added to the template itself.
- One central copy of documentation is kept
- Very minor incremental for existing templates.
Disadvantages
- Doc generator cannot embed any documentation without fetching from external site.
Hybrid Approach: Partial Embedded Documentation plus Link
Description
Provide a link inside each template to the official documentation page, as with the previous approach. In addition, embed a limited set of critical documentation or template metadata into the template itself, to enable the "doc generator" to build its table without strictly needing to fetch from the MindTouch site.
Advantages
- Small effort for new Template developers
- Template metadata enables doc generator to do useful stuff, e.g.:
- Check template version versus newest available version
- Generate summary info without fetching externally
- Primary wiki documentation still built as normal separate wiki page, using all available facilities.
- Primary documentation could extract metadata from template to eliminate need to document twice.
Disadvantages
- Documentation is split across two places
- Still need to define a markup format
- Slightly more work to update existing templates.
Open Issues
- Should extensions be included in this effort, to provide unified documentation of templates and extensions?
- Ideally yes, but practically it will be difficult to achieve. Therefore we will proceed with a templates-only solution for now. Any thoughts on how to pull in extensions are welcome, though.
Discussion
 #1 | neilw at 07/03/2010 - 03:53 @carles.coll
Check this out, see what you think (it was your suggestion a while back which inspired it after all). I'm really happy with this solution, and think it should work well. Still need to work out some details before deploying. Check out the First Test page for the system in action. |
#2 | carles.coll at 07/03/2010 - 07:28 @neilw - Some questions :
- The div templateSelfDocumentation when you say it's skiped on instantiate, where you mean?
1. Edit page > Icon Insert template
2. {{ Template(); }}
Hey that's the starting point of autoinstall templates ( check version and update a template from a central repository... ), I was thinking on this yesterday.
Anyway this rocks!!! No way with the other aproaches. |
#3 | neilw at 07/03/2010 - 21:04 @carles.coll
By "instantiate" I actually meant *call* the template, versus pasting it in with the "insert template" button. I don't know a good word to distinguish the two.
Yes, auto-install/auto-update is theoretically possible, as long as we put sufficient information. If you can think of anything else that needs to go in, let me know. I'd like to nail down the part that goes into the template itself, then the "templateDoc" template can evolve as it needs to. |
#4 | carles.coll at 07/03/2010 - 21:52 @neilw
I have "half in the mind" something more we need, I had done templates for customers, then you have to document the interface itself nor the template call. I'm thinking on a Help Link on the instantiated template that goes to a help page, this page has to be apart of template.
Also In my apps I have the concept of widged and the concept of applications:
- Widget -> A template that gets embedded on pages or aplications
- Aplications -> A template that uses one or more widgets and some input data to fill the entire page.
I have done some intereting documentation and tag related structure to auto document part of it.
... |
#5 | neilw at 07/03/2010 - 22:03 @carles.coll
The tough thing is that you can't put working examples on the template page itself... so at some point you *need* to have a separate documentation page. That's why, for now, I stopped where I did. |
#6 | carles.coll at 07/03/2010 - 22:36 #5: @neilw
I don't see a problem to have on separate pages, we can find easily via a specific tag o via a link on the template itself, I think the structure you propose its enought, just add a section to link aditional pages maybe (examples, aplication documentation, resource page,...)
Maybe It needs a section for dependences to other templates ( Its kinda packages as you mention on TemplateDoc demo todo ). |
#7 | neilw at 07/03/2010 - 22:48 #6: Well, we have the doc page link already in the template, though I have it now as a plain text URL rather than an actual link (to make it simpler and more foolproof for the template creator).
As for other dependencies, if we put them in a new section then we could add it later without harming anything right now. If you know of anything that would need to be changed in the current structure to support it let me know. I have no idea at the moment how to really handle dependencies, so the only thing I can think is "we'll add it later". |
#9 | neilw at 08/03/2010 - 20:40 @carles.coll @rberinger
I've added a to the "templateDoc" page. Inside, I'm putting s with critical metadata that a remote wiki might want to fetch. For now I've identified:
1) current version number. This enables the remote wiki to easily determine if its current version is up-to-date or not. Technically, it could just find it in a table (like it'll need to do when figuring out its own template version number) but it seems nice to stick it in its own place.
2) template source URI. This is a fully constructed URI to enable the remote wiki to fetch the latest source code. One-click template updating here we come!
The remote wiki template to take advantage of this stuff has yet to be written of course, but this puts in place the capabilities to make it happen. Does this look OK, and are there any additional metadata fields I should include in the first iteration?
See http://developer.mindtouch.com/User:neilw/Template_Self-Documentation_Project/TemplateDoc_demo for code and details. |
#10 | carles.coll at 09/03/2010 - 19:05 #9: @neilw For the moment I don't see any more needs. |
- Tag page
- What links here
| Images 0 | ||
|---|---|---|
| No images to display in the gallery. |
Copyright © 2011 MindTouch, Inc. Powered by
Check this out, see what you think (it was your suggestion a while back which inspired it after all). I'm really happy with this solution, and think it should work well. Still need to work out some details before deploying. Check out the First Test page for the system in action.
- The div templateSelfDocumentation when you say it's skiped on instantiate, where you mean?
1. Edit page > Icon Insert template
2. {{ Template(); }}
Hey that's the starting point of autoinstall templates ( check version and update a template from a central repository... ), I was thinking on this yesterday.
Anyway this rocks!!! No way with the other aproaches.
By "instantiate" I actually meant *call* the template, versus pasting it in with the "insert template" button. I don't know a good word to distinguish the two.
Yes, auto-install/auto-update is theoretically possible, as long as we put sufficient information. If you can think of anything else that needs to go in, let me know. I'd like to nail down the part that goes into the template itself, then the "templateDoc" template can evolve as it needs to.
I have "half in the mind" something more we need, I had done templates for customers, then you have to document the interface itself nor the template call. I'm thinking on a Help Link on the instantiated template that goes to a help page, this page has to be apart of template.
Also In my apps I have the concept of widged and the concept of applications:
- Widget -> A template that gets embedded on pages or aplications
- Aplications -> A template that uses one or more widgets and some input data to fill the entire page.
I have done some intereting documentation and tag related structure to auto document part of it.
...
The tough thing is that you can't put working examples on the template page itself... so at some point you *need* to have a separate documentation page. That's why, for now, I stopped where I did.
I don't see a problem to have on separate pages, we can find easily via a specific tag o via a link on the template itself, I think the structure you propose its enought, just add a section to link aditional pages maybe (examples, aplication documentation, resource page,...)
Maybe It needs a section for dependences to other templates ( Its kinda packages as you mention on TemplateDoc demo todo ). edited 12:38, 7 Mar 2010
As for other dependencies, if we put them in a new section then we could add it later without harming anything right now. If you know of anything that would need to be changed in the current structure to support it let me know. I have no idea at the moment how to really handle dependencies, so the only thing I can think is "we'll add it later".
I've added a <div id="templateMetadata"> to the "templateDoc" page. Inside, I'm putting <span>s with critical metadata that a remote wiki might want to fetch. For now I've identified:
1) current version number. This enables the remote wiki to easily determine if its current version is up-to-date or not. Technically, it could just find it in a table (like it'll need to do when figuring out its own template version number) but it seems nice to stick it in its own place.
2) template source URI. This is a fully constructed URI to enable the remote wiki to fetch the latest source code. One-click template updating here we come!
The remote wiki template to take advantage of this stuff has yet to be written of course, but this puts in place the capabilities to make it happen. Does this look OK, and are there any additional metadata fields I should include in the first iteration?
See http://developer.mindtouch.com/User:neilw/Template_Self-Documentation_Project/TemplateDoc_demo for code and details.
This isn't quite finished, but it's getting there and you might want to have a look. It occurred to me that this approach will conflict with the "DekiScript-only" pages that you proposed, and that would be a bummer. Any thoughts?