New tutorials and manual ideas

[dcwhite]

From discussion in #1513:

@jessdtate:

As general feedback on the tutorial, it probably needs an update to the introduction, ie, and explanation of some of the preferences and features that are available. Maybe it can walk through the startup wizard. This might be better suited in a 'Getting Started' doc though.

@zaracay:

There needs to be some sort of installation instructions and an introduction that explains why you show the examples that you chose.

[rsmacleod]

Some comments on the technical side. Content is a separate question we will need to address too. These comments come from the SCIRun tutorial pointer you sent me:

1. Layout is too open, fonts too large, too much wasted white space around the text in the section titles.
2. There really need to be better navigation tools, at least a table of contents. Better, will the system automatically make separate pages somehow? LATeX2html, which I would not otherwise recommend, had at least one nice feature in that it would create a links table that propagated around the separate pages it would also create. One could control the mapping between LaTeX section level and the separate pages of the resulting html. Something like this would make this long, single document more manageable and web friendly. Ideal would be both options, i.e., a link to a single-page version and a link to a multipage version.
3. Figure captions poorly formatted. They run off the right edge of the images rather than with a carriage return so that they appear below the images where they belong.
4. None of the Figure references in the text seem to be live links. Even LaTeX can make a pdf with live links, so surely we need this in our web based documentation.
5. Section 3.4 Clip Field has a passage " DAT**A1 > 1&&X < 0 t" that also has the "A" bolded. This looks ugly and I have no idea if it is also correct. I did not look at the LaTeX original but it appears we have to be careful about how LaTeX formatting makes it to markdown. This could get really tedious if we have a lot of it.
6. The main (or only?) advantage of markdown was supposed to be that a reader could fix errors but I see no obvious buttons or options that would allow this. How do we provide such links and how to we manage who will see them? I assume there is a need to log into the syste before editing is allowed but where does this happen? To me, it should be an obvious link on the page somewhere.
7. We need versioning for all documentation. Is there a way to show in the display of the documents the version for that document? This might need some sort of document database but even if we have to manage it manually, I think this is essential when we are trying to keep up more than one version of things. It is also necessary because we will never have all the documentation at the same level as the software, i.e., some parts of the docs will be at least slightly out of date and we need a way to mark each document accordingly. The example you pointed me at has no obvious version number.

[github-actions]

Stale issue message

[dcwhite]

@jessdtate We should review this one with @nids2001.

[jessdtate]

yes

[github-actions]

This issue is stale because it has been open 120 days with no activity. Remove stale label or comment or this will be closed in 60 days.

[github-actions]

This issue is stale because it has been open 240 days with no activity. Remove the stale label or comment, or this will be closed in 60 days.

[github-actions]

This issue is stale because it has been open 240 days with no activity. Remove the stale label or comment, or this will be closed in 60 days.