Build and deploy dopcs in PDF.

Even though we only have two distinct docs at this point, the list should be generated automatically and then inserted into the landing page.

Currently, building on local requires root privileges. This should be fixed.

=== Building Guides ===
//docs
Building //docs/e2e_workshop
asciidoctor: WARNING: skipping reference to missing attribute: segmenttrackertoken
Building //docs/user_guide
asciidoctor: WARNING: skipping reference to missing attribute: segmenttrackertoken
+ chmod -R 0777 html/
chmod: changing permissions of 'html/openshift-io_user_guide.html': Operation not permitted
chmod: changing permissions of 'html/openshift-io_end_to_end_workshop.pdf': Operation not permitted
chmod: changing permissions of 'html/openshift-io_user_guide.pdf': Operation not permitted
chmod: changing permissions of 'html/images': Operation not permitted

Tracker for user stories, component and cross component : https://docs.google.com/spreadsheets/d/1Sk22jZgokdXEu4GgNDKFw2Id75lTBCvJ4u5FWxjNVfQ/edit#gid=0

Compare our E2E doc with Todd's to identify things we should cover that are in the latter.

The README file contains obsolete instructions:

• get rid of ccutil mentions
• fix mark-up in asciidoctor instructions
• get rid of references to RHDEVDOCS JIRA

Also, the process for getting docs from preview to prod needs to be documented:

(as per @Preeticp's mail)

1. Fork and clone the openshiftio/saas-openshiftio directory.
2. Replace the 'hash:' value with your commit ID in the f8-docs.yaml and raise a PR for the same.
3. Ask the maintainers to merge the PR.

Currently, docs HTML files carry all of their CSS, which is ugly and sucks bandwidth. Docs should be built with the :linkcss: attribute, and the CSS file(s) should be deployed along with the rest of the docs.

Infotips content based on OSIO User Guide Glossary needs to be converted to Markdown and then JSON with the following structure:

{
  "tooltips": {
    "id_tooltip_0": { "en_EN": "Some **markdown** text." },
    "id_tooltip_1": { "en_EN": "This can also include linebreaks." }
  },
  "infotips": {
    "id_infotip_0": { "en_EN": "Some **markdown** text." },
    "id_infotip_1": { "en_EN": "This can also include linebreaks." }
  }
}

IDs to be generated as UUID.

There will be a separate file for tooltips and infotips, which will be served as:

https://docs.openshift.io/json/infotips.json
https://docs.openshift.io/json/tooltips.json

• Creating WI
• Modifying WI
• Working with/using Planner
• About WI/Planner

The timestamp in index.html only needs to be updated when built in OpenShift, not on local. We don't want to deal with a modified index.html file that would either need to be committed (useless) or resetted (overhead).

The header logo points to /docs/index.html, but it should go to /index.html.

When building guides on local by using the bare scripts/build_guides.sh script, don't build PDFs because it takes too much time.

No change when building in the container.

References:
Existing FAQ: https://github.com/openshiftio/openshift.io/wiki/FAQ

Burr's Hello World Videos (ref: https://docs.google.com/document/d/1OszzoSyv2gqv8mlSg1yHeBxMAk9v4rGCKg_FkfN_d7w/edit#heading=h.a5lc9uymo7qx)

Steps:
https://docs.google.com/spreadsheets/d/1B2ckTXCsKc8sD_S2p7OP7d1fvcMI8_6tjTosT3ihSMM/edit#gid=547154663

#11

Both docs (E2E, UG) need some meta info:

• authors + sources
• where to file bugs against the docs
• how to contribute (i.e. link to repo's README)

following the asciidoctor instructions https://github.com/fabric8io/fabric8-online-docs#using-asciidoctor I get these errors:

git clone https://github.com/fabric8io/fabric8-online-docs
cd fabric8-online-docs/user_guide
asciidoctor --section-numbers --attribute=toc master.adoc*

asciidoctor: ERROR: content/user_guide.adoc: line 4: only book doctypes can contain level 0 sections
asciidoctor: ERROR: content/user_guide.adoc: line 12: only book doctypes can contain level 0 sections
asciidoctor: ERROR: content/user_guide.adoc: line 12: only book doctypes can contain level 0 sections
asciidoctor: ERROR: content/user_guide.adoc: line 12: only book doctypes can contain level 0 sections
asciidoctor: ERROR: content/user_guide.adoc: line 12: only book doctypes can contain level 0 sections

Our common attributes should set the sectlinks and sectanchors options to simplify deeplinking.

See http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#section-titles for reference.

Test generating the doc HTML with the TOC to the side. See @mishaone's comment at #40 (comment) for more.

@rawlingsj, could you please take a look at the Jenkinsfile and fabric8-online-docs-app you prepared for this repo? We had to change the repo's structure to unify it with RHOAR/LOSIO docs, but that broke the pipeline you set up.

I'd be happy to provide additional information or try to fix it myself if you point me in the right direction.

Use styles developed for RHD to render OSIO docs.

https://github.com/fabric8-launch/appdev-documentation/tree/master/docs/topics/styles

In fabric8-online-docs.app.yaml Line 101 the image pull url is incorrect. This results in failed pods with ImagePullBackOff.

Run the deploy container when building docs on local.

Review and update all modules in the E2E document.

The e2e directory under modules was only introduced because we thought the e2e doc will be phased out. That's not the case, so we want all our modules to live in the same directory.

@mishaone, @Preeticp, take note -- this will be another big restructuring. However, it will be very straightforward. We will just move all modules from modules/e2e/ to modules/.

• Need to build both "User Guide" and "E2E Guide".
• Landing page needs to be added with links to ^ docs.

Local builds using scripts/build_guides.sh that follow local builds using the Docker method throw the following errors:

...
chmod: changing permissions of 'fabric8-online-docs/html/e2e_workshop.pdf': Operation not permitted

The landing page (https://docs.prod-preview.openshift.io/) is butt-ugly. It should be improved to not be an embarrassment.

@joshuawilson, could you please advise who to approach for help with this?

The docker commands in cico_build_deploy.sh need a clean up.

We need support for icons from PatternFly and Font Awesome for showing UI widgets and elements.

As a second step, currently used mini screenshots of the same widgets and elements need to be replaced by the scalable icons.

References:
Burr's Hello World Videos (ref: https://docs.google.com/document/d/1OszzoSyv2gqv8mlSg1yHeBxMAk9v4rGCKg_FkfN_d7w/edit#heading=h.a5lc9uymo7qx)
Steps:
https://docs.google.com/spreadsheets/d/1B2ckTXCsKc8sD_S2p7OP7d1fvcMI8_6tjTosT3ihSMM/edit#gid=547154663

Until a new landing page is ready (#40), the timestamp in the footer should be at least updated automatically.

Review the UG and update all the content modules.

@mishaone, @Preeticp, at your convenience, please, check the UG (at https://docs.prod-preview.openshift.io/) for any formatting or rendering problems that may have been caused by the application of the new styling. For reference, this is the LOSIO docs from which the styling was taken: https://appdev.openshift.io/docs/minishift-installation.html

Two known issues I'm working on:

• logos in the header and footer of the page are not showing
• doc timestamp isn't displayed

Draft ready, adding final touches, PR coming soon.

Our mark-up should observe conventions set forth in https://redhat-documentation.github.io/asciidoc-markup-conventions

Some of these changes can be automated, the rest will need to happen manually.

To provide a consistent feel, action headings should all use gerund forms. E.g. consider:

7.13. Changing the quickstart code
7.14. Commit and push changes to GitHub
7.15. Review and publish your changes
7.16. Closing a work item

The middle two headings should be converted to:

7.14. Committing and pushing changes to GitHub
7.15. Reviewing and publishing your changes

@qodfathr: Furthermore, I feel we need more documentation which explains the "why's" of OSIO; today there is a lot of "how's", but I feel that important, high level messages are being lost. Something like a "day in the life" story could possibly help.

Looking for more input.

Some terms have evolved and need to be updated.

the user guide and on boarding documentation were based, in part, upon other non-canonical (e.g. the first several revisions of the workshop document) or outdated sources (e.g. the glossary) and, as such, has issues related to the naming of things, the messaging behind certain capabilities, etc. (e. g. OSIO has neither Projects nor Collaboration Spaces, both of which are older, deprecated terms.)

Use Todd's GSG as reference: https://drive.google.com/file/d/0B84xd3xHpx5cNlRuaC1aM1NsMVk/view

Expand on the spaces module. Preeti's comment for context:

But just wanted to add this note, so that we do not lose track of it, IMHO we need to flesh this topic out more. At the time we had got in whatever little content we could gather. I guess we need to follow up with the Platform team for more information. For instance, the relation of templates with space, which determines the Planner WIs etc.

This would be channeled into Infotips for the UX as part of the contextual help.

Files such as docinfo.xml are required by downstream publication toolchain. They should be removed to avoid confusion.

Currently, each guide requires its own build script. This is cumbersome and unnecessary. The main build script should be modified to be able to automatically build all guides by itself.

I am transcribing the mail discussion here to keep track of these discussions in one place.
Summary of Meeting:

• Misha to flesh out the E2E experience doc, Preeti to help provide content for the Analytics portion.
• Preeti to work on the Troubleshooting Doc, test and update steps.
• Both of us would be testing the steps in the E2E and adding issues to the Trouble shooting. This would also help us review each others docs.
• Spoke of possible User stories involving individual components like Planner/Analytics alone and stories involving 2/3 components too.

Possible user stories from Planner and Analytics POV as of now:

1. How Authorization determines various views in Planner;
2. Planner in sync with Platform-Platform integrates and provides the Planner a backbone;
3. Planner by itself has 3 User Stories based on the end user
4. Analytics primarily working with OSIO and its various functionalities, interacting with CHE, Pipelines and Planner
5. Analytics integration with Devstudio and Visual studio

I can't see the previews at the moment, but I think they also have this issue.

Currently, for everything that is not marked up, the docs font renders in a way that makes every lowercase i look like a lowercase L. See screenshot for examples of this:

Expected behavior is that the lowercase i should clearly look different from a lowercase L.

ID anchors should be formed and formatted based on recommendations in https://redhat-documentation.github.io/modular-docs/#anchor-and-file-names

The syntax part can be converted automatically. The content possibly too, but first we need to fix the headings.

File names should reflect the module or assembly title to make it easy to find in the repo for anyone making changes.

Currently I'm reorganizing and changing (and removing) a lot of files so holding off on this till I'm done with that and can focus on just this task (and ensure nothing is left out) due to the file name change plus that it's the final proposed titles for the modules, since this is also changing at this time.

What does this sentence at the end of the e2e guide mean? Can it be removed (or commented out)?