VASL documentation

[wintrymix]

Apologies for the delays getting to work on the VASL documentation, but life was getting in the way for a while.

I proposal to develop the documentation using Darwin Information Typing Architecture (DITA). DITA is an open-source XML architecture that has been adopted by a number of organizations. You can find more information in a number of places, but here is one place to start. http://www.ibm.com/developerworks/library/x-dita1/ (BTW, if you Google DITA, be aware that there is a pornography actress named Dita von Teese, as well as a line of DITA sunglasses, so the safer course is to Google the fill term to avoid that kind of confusion.)

Being an open-source XML architecture, a proprietary editor is not required to develop the content (unlike a number of other documentation options). All the user needs is an XML editor. (You could even use a simple text editor, but an XML editor brings a number of benefits.) Moreover, because it is XML, the source can be easily managed in the same repository as the VASL source code.

The standard publishing engine for DITA is the DITA Open Toolkit (DITA OT). The DITA OT is an open source tool (http://sourceforge.net/projects/dita-ot/?source=navbar) that uses a combination of Java and XSL stylesheets to produce output. Processing is driven by ant, so it can be easily integrated into a software build system. In addition, the toolkit is designed to be both extensible and customizable.

The DITA OT publishes to a variety of outputs, including PDF and EPUB, as well as several varieties of HTML. So we can produce an integrated, HTML-based help system for the VASL interface, as well as any PDFs that we think might be appropriate (such as an installation guide), all out of one source repository.

We would need to determine the appropriate HTML output to use to support the VASL interface. The best options are Eclipse Standalone Help or HTML with JavaScript TOC. See this link for details about implementing Eclipse Standalone Help: http://help.eclipse.org/luna/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Fguide%2Fua_help_setup_infocenter.htm. I think this could be integrated into the VASL interface fairly easily, and I think we might be able to use the existing context-sensitivity capability. Another benefit of this option is that it is easily extendable. For example, plugins could extend the help by hooking into the base VASL help plugin.

Any of the other HTML options would require more programming work to call the Help and yet further work to implement any form of context-sensitivity. Moreover, these formats would not be extensible. We would either have to incorporate the plugin content into the base VASL help (not really an option for third-party extensions) or publish different version of the help based on the combination of extensions supported (functionally impractical) Or, more likely, the plugins would simply be unsupported in the interface help.

I think my preference is clear, but you guys have a say as you will implement the interface to the Help.

I think the priority right now is to get some form of Help system implemented and integrated into the VASL interface, then developing an installation guide. Then we can address other documentation needs of the project.

The only programming that you guys must do is integrate the Help with the VASL interface. Beyond that, it would be ideal to integrate the documentation builds into the software builds.

I can start developing the DITA source immediately while we discuss the HTML format we want to implement and whether to integrate the documentation builds into the software builds.

[zgrose]

I think the priority right now is to get some form of Help system implemented and integrated into the VASL interface, then developing an installation guide. Then we can address other documentation needs of the project.

I personally don't see much use for a standalone, offline help system when we could just link to vasl.info or the GitHub wiki pages and kill two birds with one stone. IMO, the GitHub wiki would be the best place for VASL docs. Cheap, available and easy to use for authors and editors.

[davidsullivan317]

I'd second the idea of using vasl.info. People could bookmark it and it should be straight forward to have the VASL help menu open the web page in VASL at some point.

[mistertakai]

I would recommend to keep all documentation in the GitHub Wiki, where the developers can control it. No deployment process necessary. No dependency on an external hosting contract. It's also well readable on mobile devices.

[uckelman]

What about offline help?

[davidsullivan317]

I guess I don't have strong opinions on the wiki vs. vasl.info but we should do one or the other, not both. I would still lean toward using vasl.info because 1) the vasl.info is under source code control, so developers do control it and 2) the wiki only supports esoteric editing formats. Plus users would then have two websites to deal with/remember.

[wintrymix]

If we follow this option, I recommend using the wiki for developer documentation and vasl.info to host and deliver the end-user documentation.

Wikis were very popular for maintaining and delivering documentation 5-6 years ago. The never lived up the promise (hype?). In fact, most of the popular commercial wikis have rebranded themselves as "collaboration platforms". The one use case for which wikis proved effective was developer documentation.

I did a view source on a couple of vasl.info and it does not look to me like there is a content management system behind them; the pages look hand-coded to me. We're probably looking at quite a bit of content to maintain. Without a CMS, I still think DITA is the right way to maintain the content, The content would be published to an HTML output that could then be uploaded to the vasl.info site. The DITA source can be maintained in the git repository.

[davidsullivan317]

Chat with Sam - he's currently maintaining the vasl.info website. The source is in the sister repository: https://github.com/vasl-developers/vasl-website

[mistertakai]

An alternative to create the end user documentation would be to use GitHub pages technology to maintain it. You get a templating engine and blogs and it's pretty straight forward. Deploment is automatic on commit. By using branches you can establish a simple workflow for staging changes to the documentation. I'd sure pitch in to help with setup and process documentation here.

[wintrymix]

I need a couple of clarifications about LOS checking so I can complete the doc updates.
I assume the Silent LOS check is only visible to the player checking LOS, not to the opponent. Is that correct?
The current page on LOS checking says checking for the following terrain transformations is not supported: Orchard to Shellholes Orchard to Crags Shellholes to Orchard Shellholes to Crag Are the corresponding Crag transformations (i.e., Crag to Orchard and Crag to Shellholes) similarly not supported?

[davidsullivan317]

I assume the Silent LOS check is only visible to the player checking LOS, not to the opponent. Is that correct?

Correct.

Are the corresponding Crag transformations (i.e., Crag to Orchard and Crag to Shellholes) similarly not supported?

Crags to Orchard and Shellholes is supported. The problem with the other transformations is handling roads, which adds too much complexity.

[bkemp01]

FWIW as a general rule I believe the map elves have avoided placing crags on roads. i.e. an orchard-road becomes just a road under the orchards to crags transform.

On Sun, Nov 30, 2014 at 10:05 PM, David Sullivan notifications@github.com wrote:

I assume the Silent LOS check is only visible to the player checking LOS, not to the opponent. Is that correct?

Correct.

Are the corresponding Crag transformations (i.e., Crag to Orchard and Crag to Shellholes) similarly not supported?

Crags to Orchard and Shellholes is supported. The problem with the other transformations is handling roads, which adds too much complexity.

— Reply to this email directly or view it on GitHub https://github.com/vasl-developers/vasl/issues/125#issuecomment-65015657 .