Write tutorials at /resources/documentation/

[isimluk]

Or remove them before release.

[mpreisler]

The way the system works we can unpublish the empty tutorials so I'd say it's a release blocker to publish the portal with some tutorials.

I take it as my goal to provide empty tutorial pages with titles and references to sources as I promised 3 meetings ago.

TODO of this issue:

• http://openscap-lhorakov.rhcloud.com/resources/documentation/ to link to user manuals

Depends on:

• 30

• 31

• 32 - nearly done

• 33

• 34

• 35

• 49

• 54

• 55

[mpreisler]

Blog pages that could be turned into tutorials if we decide it has value:

• http://isimluk.livejournal.com/3660.html + http://martin.preisler.me/2012/12/introduction-to-scap-datastreams-with-openscap/ + http://isimluk.livejournal.com/5655.html
  • how to deal with datastreams
• http://isimluk.livejournal.com/4043.html http://isimluk.livejournal.com/2264.html http://isimluk.livejournal.com/2019.html http://isimluk.livejournal.com/1027.html (Sat5 SCAP)
• http://martin.preisler.me/2015/05/scanning-remote-machines-with-openscap/
• http://martin.preisler.me/2015/06/customizing-html-reports-guides-openscap/ (probably too technical / niche)
• http://isimluk.livejournal.com/3573.html - how to remediate
• oscap info - introspecting SCAP content? - http://isimluk.livejournal.com/3202.html
• distribute SCAP content - scap-as-rpm - http://isimluk.livejournal.com/1776.html

more? please add here, I am sure I have forgotten some :-)

[mpreisler]

@isimluk noted that there is overlap between user manual and some of the tutorials. I definitely agree. Let me summarize why I think both can co-exist.

• Tutorials
  • hands-on examples for every step
  • require minimal previous knowledge
  • are very specialized, it is up to the reader to figure out how to change the use-case -- they can do that by reading the user manual
  • very verbose
  • short -> motivating
• User manual
  • more technical, doesn't have as many pictures
  • not as verbose but covers a ton of material -> very long
  • a chapter usually requires knowledge of previous chapters
  • generic, tries to cover lots of use-cases at once

As an example the tutorial covering a chapter in user manual will also say how to install openscap, will show screenshots, will list expected output of calling the steps, etc...

User manual is usually used by people who are already familiar with the basics. Tutorials are used by newcomers.

If there is 100% overlap we can slightly change the direction of some tutorial to be more complementary to the manual. The titles as well as the URLs are subjects to change.

[isimluk]

Nod.

The tutorials are now linked from the resources/documentation page. So, I think we can close this ticket. Please re-open if disagree.

We are tracking each tutorial at separate tickets (thanks!!).