Link Wiki help from the program

[missyschoenbaum]

I have a couple of wiki questions.

First, if you are running out of things to do, can we attempt to hook up the wiki somewhere? I trust @ndh2 's documentation the most, so maybe we can pick a place where it is appropriate.

Second, I quickly skimmed the old documentation we have in the wiki. Some portions will need a major visual rework to show the new app. I don't really want to do a major documentation rework until I have TJ's input. Maybe that is a statement more than a question.

[josiahseaman]

I was going to start writing #178 documentation into the wiki. I'm not exactly running out of things to do, I was just trying to put the timeline in perspective. I have at least a month's worth of work to do. I don't really know what "hook up the wiki somewhere" means, but I'd be happy to do it if you can explain?

[missyschoenbaum]

Long ago we had the discussion that we can use the wiki as on-line help documentation. What does that look like? Does that mean that they push a button and pop to the whole wiki menu? (somewhat overwhleming even for me at the moment) Does it mean they are sitting on vaccination, push the button and get context specific help on vaccination? Does it mean they need a github login?

[josiahseaman]

3) They don't need a github login because the documentation will be open to the public.

2) Context specific help is definitely what we want to give people. That's why it's important to dice the wiki pages up into bite size chunks. The style of a wiki is much more like hyperlinked paragraphs than it is like a book. (Wikipedia is a bad example). Here's an example from the Minecraft Wiki. You have a very limited scope and the page just talks about the immediate connections to the topic with links that go elsewhere.

1) We're going to launch the user's actual browser for the wiki so that they can thumb around the wiki without interrupting their work. We'll drop them into the correct wiki page for their context and them let them navigate normally.

Consequently, there's a lot of work to be done on the wiki and on adding links from every point in the program to every relevant wiki page. I'm probably not the best person to do that, but I'll set up the architecture so it's just a matter of cut and pasting links.

[missyschoenbaum]

Yes, there is a lot of work to be done to both gather/write the documentation and then to decide where it links. I guess I was hoping for an small example so the people who have to do the work understand how it will be implemented.

[josiahseaman]

Good idea, can you think of a topic particularly suitable to example? Perhaps vaccination or something else in Control Protocol that's a bit simpler?

[missyschoenbaum]

I think the problem is more what we have a good bit of documentation on - and Neil's is better than what we pulled across as User's guide

[josiahseaman]

@ndh2 do you still have documentation that you'd recommend using that's not on the wiki?

[ndh2]

I have some slides on the history and internal structure of the C code that could go on the wiki. That's developer documentation though, and I think this thread is more about user documentation.

The User's Guide 3.0 for NAADSM was fantastic. It contained an introduction to stochastic modeling, a "quick start" type chapter for the software, and then detailed screen-by-screen instructions. It is under a Creative Commons license so it could be used as a starting point for updated documentation. It is in PDF format however and I don't have sources.

[missyschoenbaum]

I don't think I have V 3. in word, but I did have to review what I think was V.4 in my very first weeks here. Columb and I both had edits and sent them to Aaron, but he didn't choose to implement them. I remember having the technical writers look at it, and they had suggestions also.

I will see if I can find that and get the tech writers on it. I would aim for just the short section that is the intro to stochastic modeling.

[missyschoenbaum]

OK, I found the version that I reviewed and it was V 3. I am going to funnel it through the tech writers to get their suggestions implemented.

There are images in the document. I remember the wiki didn't seem to like images. Should we try to avoid them?

[missyschoenbaum]

The editor says he can't get to it until Wednesday (9/24) but it is in the pipeline.

[josiahseaman]

@ndh2 PDF is unfortunate, but we can work with it. If Missy has Word docs, that'd be a bit better. It sounds like just proof reading for V3 specific stuff should work out okay. We can even have "New in V3" tags to denote differences. That's what plenty of other documentation sites do.

@missyschoenbaum there's nothing wrong with images at all. Neil and I just had to figure out how to host the images online. The technical writers can download and use Git for Windows and it'll take care of all the details for them. You just drop files into a folder on your hard drive and tell Git for Windows to sync them online. Then you can link those files in the wiki. It works fine, there's just no "Upload" button on the wiki editor itself.

[missyschoenbaum]

I have the reviewed copy, but the graphics are a disaster. It will take me a bit to recreate.

I know we need to reference that the text was adapted from old Users Guide. Do I just put a line at the bottom that says that? Like " Text adapted from the User's Guide for the North American Animal Disease Spread Model 3.2"

I have this from the document User’s Guide for the North American Animal Disease Spread Model 3.2 Copyright © 2005 – 2013 Colorado State University. Third edition, third printing, February 26, 2013 Permission is granted to copy, distribute and/or modify this document under the terms of the Creative Commons Attribution-NonCommercial-ShareAlike 2.5 License. Please see http://creativecommons.org/licenses/by-nc-sa/2.5/ for details

[josiahseaman]

Yup, if you want to use it you'll need to attribute the source. We can just make a footer that can be imported from every relevant page. I think the graphics will need to be replaced with the new UI anyways, so there's no problem there, is there?

[missyschoenbaum]

This section doesn't really refer to the model. It just covers the concept of stochastic modeling. The images support the text.

[missyschoenbaum]

OK, I have gotten this edited, simplified and got one of the images cleaned. I will work on uploading it.

[missyschoenbaum]

Adventures in Github - I used my local github and pushed up a version of a file called Basics of Stochastic Modeling - it says it committed it to production-testing. Do I need to do anything else?

[josiahseaman]

Looking through all existing branches I don't see the commit anywhere. That most likely means you never hit 'synchronize'. I'd like you to do a couple things.

1. backup your file so you don't lose it
2. switch your branch to gh-pages, this is the branch with all the wiki content
3. make a commit in gh-pages with your new file
4. press the "Synchronize" button which will actually upload your file to the remote server. Synchronize looks like a two circular arrows.

[missyschoenbaum]

ok - did it make it?

[josiahseaman]

Take a look: https://github.com/NAVADMC/SpreadModel/commits/gh-pages

All commits are visible on GitHub under the "Code" tab. You select which branch you want (gh-pages) and then click on "Commits". If you want to make your commits easier to find, the GitHub Ettiquette recommendation is that you mention the Issue number #245 in the commit message. Then GitHub will automatically link it.

Or you can paste the SHA to a commit: 057a50fbb0aab65bb9810dc9a3431d99dcf780b4

The file you uploaded is now available to everyone, though it's a docx file, which you won't be able to embed in the wiki. We use SVG, PNG, JPG, and HTML. A good fallback is just plain old TXT so at least we can copy the content. If your doc has an image in it, you'll want to right-click on it and export/save as a regular PNG/JPEG image.

[missyschoenbaum]

OK, should I try it again as plain text? And do I send both the text and image file up? and do I use #245 or just plain 245?

[josiahseaman]

The # sign is key to letting GitHub know it's an issue number. You'll need to upload the images individually. I would just create a new wiki page and paste the text in, rather than uploading a text file.

[missyschoenbaum]

OK, new wiki page created, looks fine except I missed how to connect the image.

[missyschoenbaum]

Next question along the lines of documentation. I have glossary items from "Lexicon of disease spread modeling terms". If we want to use this as contextual help, how do I proceed. The document is a simple list of terms with their definitions. Not all of them are relevant as items that would have a direct link to contextual help (eg AusSpread - nice to know but not referenced within ADSM).

[josiahseaman]

In order to put the Image on a wiki page you need to get the hyperlink for the image. Here's what I did:

• Code tab
• branch dropdown: gh-pages
• link: Fig3-1_heightdistrchart.png
• "raw" button
• copy the url from my address bar

I get: https://raw.githubusercontent.com/NAVADMC/SpreadModel/gh-pages/Fig3-1_heightdistrchart.png

Now I navigate to your page and click edit, then the "image" button. I paste in the above link and it generates the appropriate Markdown to add an image. If you like writing your own HTML you can also stick tag in there by hand.

[josiahseaman]

The Lexicon text file that you emailed me should be cut and pasted from the word document into the wiki. PDF is a bad format to cut and paste from because it doesn't contain information on what order the text should be read in (columns, pages, footers, etc.). GitHub wiki uses Markdown for formatting. I can format the text if you're not interested in learning Markdown.

[missyschoenbaum]

OK, so we put the whole thing into wiki in one block and then you can context link to distinct definitions - link to direct contact from the direct contact page?

[josiahseaman]

Yes, when you mark things as headers using Markdown it will generate sublinks which you can link to inside of the wiki page. If you want all word mentions in the definitions linked to all other words then I'll just write a script to automate that.

[josiahseaman]

https://github.com/NAVADMC/SpreadModel/wiki/How-to-Install-ADSM

https://github.com/NAVADMC/SpreadModel/wiki/User-Guide%3A-Running-the-sample-scenario

[josiahseaman]

FYI I've been working on this issue most of today but there won't be a code commit. I've added and reformatted the Lexicon.

https://github.com/NAVADMC/SpreadModel/wiki/Lexicon-of-Disease-Spread-Modelling-terms

I'm working on a script to hyperlink all header mentions inside the text.

[josiahseaman]

Phew, done with all the links. That took a lot longer than I expected.
https://github.com/NAVADMC/SpreadModel/wiki/Lexicon-of-Disease-Spread-Modelling-terms

Fun fact: "NAADSM (North American Animal Disease Spread Model)" is the longest title in that article. Naturally, it doesn't mention ADSM, which is a bit odd for our own Lexicon. @missyschoenbaum would you like me to add an entry for that? I've already changed a lot of the formatting, like moving synonyms down to the next line.

Now I'm going to head over to the ADSM source code and put links to the lexicon in the ADSM program. Bryan is already working on a solution for special hyperlinks that launch the user's default browser.

[missyschoenbaum]

Yes, let's add an entry for ADSM. I will see if someone can help on the other definitions.

[josiahseaman]

ADSM

Synonyms: Animal Disease Spread Model
The current development fork of NAADSM being developed through the USDA as a group effort between the United States and Canada. ADSM has an updated User Interface based on web technology and can be used as a server to run many iterations in parallel.

[josiahseaman]

Other definitions that would help:

• Production Type
• Unit
• Disease progression
• Population
• Zone
• contact rate (is this adequate contact or not?)
• destruction
• vaccination program
• infection probability (how does this affect the adequate contact reporting?)
• movement rate (I doubt this is the walking speed of cattle)
• Lab tests (control protocol)
• Exams (control protocol)
• indemnification (just not a very common word outside of certain circles)

Some of these may just need expanded help text, but the exact definition and usage in the simulation is not obvious, even if the general gist of the word is obvious. It's not clear to me the inclusive and exclusive scope of each word in the context of ADSM. What is the scope of a "Vaccination Program" and how is that actually modeled in the simulation?

[josiahseaman]

I've consolidated and expanded the list of needed definitions above. With all these definitions added, we'll have a significantly different document than the technical paper we started out with, so @missyschoenbaum may want to change the way the paper is cited.

I'm reassigning this issue to you since the code is done it's just a documentation matter.

Help text in orange:

[missyschoenbaum]

That is fabulous!

[josiahseaman]

Thank you. All these links are tagged with "wiki" in the code, so TJ will be able to assign them special behavior and styling. I expect it will look something like a popover definition:

[missyschoenbaum]

OK, I have gathered most of these but will need an edit and a review. Making progress.

[josiahseaman]

Do you want the update of definitions to be grouped with the official release milestone, or should I move this issue elsewhere?

[missyschoenbaum]

I think we will make it within the Official release, even if we go with only the Lexicon. But adding definitions could be considered ongoing. Should it sit in future features?

[josiahseaman]

Interesting question. I use Issues like a TODO list. The fact that this issue is still open tells me there's something more that needs to be acted on. That it's in the "Official Release" milestone tells me this must be resolved before we can release. Good news is, we're 70% complete. I've started working on the XML import.

[missyschoenbaum]

@josiahseaman I will forward the extra definition so you can post to Google Docs.

[josiahseaman]

Definitions have been added to the wiki. In the future, people can edit the wiki directly.

There's a systemic typo that may or may not be worth mentioning. Our program is called ADSM, not AADSM as far as I know. I think the N was just deleted of NAADSM. But the first A stands for America. I think our goal is be more inclusive than that.