Skip to content

Latest commit

 

History

History
257 lines (174 loc) · 7.46 KB

slides.md

File metadata and controls

257 lines (174 loc) · 7.46 KB
Raw

% Documentation
as a Code % Igor Khorlo { width=200px style="background:none; border:none; box-shadow:none; vertical-align: middle;" } % June 28, 2018
PhUSE SDE
📍 Basel, Switzerland

The problem

Why do we need documentation?

  • Standardize software usage
  • Help users to get started
  • Documents processes

How do you manage documentation?

  • Do you use Microsoft Word?
  • CMS?
  • Sharepoint?

{ style="text-align:left;" }

Right way

  • Semantically maintain styles across a document

Wrong way

  • Arial, 16pt, bold
  • Times New Roman, 11pt

Disadvantages of WYSIWYG approach

  • Keeping content and styling together.
  • Hard to review changes over many versions (track changes).
  • Hard to maintain several formats at once: HTML, DOCX, PDF, etc.
  • Very hard to collaborate.
  • Hard to automate.

Approach

Separation of concerns

{ style="background:none; border:none; box-shadow:none;" width=1000px }

{width=75%}

Welcome to our community!
=========================

**Write the Docs** is a global community of people who care about documentation. Our primary gathering places are:

* :doc:`Our slack network </slack>` with thousands of members
* :doc:`Conferences </conf/index>` on 3 continents
* :doc:`Local meetups </meetups/index>` in over 30 cities

We consider everyone who cares about communication, documentation, and
their users to be a member of our community. This can be programmers,
tech writers, developer advocates, customer support, marketers, and anyone else who wants
people to have great experiences with software.

Our conferences create a time and a place for the global community of
:doc:`documentarians` to share information, discuss ideas, and work together
to improve the **art and science of documentation**.
You can `join our Slack <https://slack.writethedocs.org/>`_ if you aren't already a member.

.. note:: Feel free to send a Pull Request to update `this page`_, if you want to include other channels.

.. _this page: https://github.com/writethedocs/www/blob/master/docs/slack.rst

Default channels
----------------

Everyone who joins the Slack will be added to these channels:

* **#general** - The main channel for documentation related conversation and questions.
* **#watercooler** - For talking about things that are off-topic. Get to know folks other interests that aren't around documentation :)
* **#jobs-posts-only** - Posting or asking for jobs.
* **#wtd-conferences** - Questions and other thoughts around the :doc:`/conf/index`.
* **#meetups** - Questions and other thoughts about our :doc:`/meetups/index`.
* **#intros** - Introduce yourself! Let people know you're here, and why you care about docs :)

{width=90%}

######################
Overview of SAS kernel
######################
.. I used https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html


*************
What is this?
*************

A SAS kernel for `Jupyter Notebooks <https://www.jupyter.org>`_. Jupyter Notebooks
are capable of running programs in a variety of programming languages and it is
the kernel that enables this ability. The SAS kernel enables Jupyter Notebook to
provide the following programming experience:
******************
Load data into SAS
******************

The FILENAME statement is used to specify an external file. The
IMPORT procedure can read data from a variety of external file formats.

.. code-block:: none

    filename x "./HR_comma_sep.csv";
    proc import datafile=x out=_csv dbms=csv replace; run;
Plot a heatmap that shows the relationship between employee
satisfaction and the last evaluation.

.. code-block:: none

    proc sgplot data=work._csv;
        heatmap x=last_evaluation y=satisfaction_level;
    run;

.. image:: ./images/heatmap_satisfaction_evaluation.png
   :scale: 60 %
   :alt: Heatmap of employee statisfaction and evaluation.

{ width=35% }

:::::::::::::: {.columns} ::: {.column width="50%"} ::: ::: {.column width="50%"} ::: ::::::::::::::

Markup languages

  • Markdown
  • reStructuredText
  • Asciidoc

Generators

Benefits

VCS Blame

{width=80%}

Pull requests

Real world examples

GitLab

{width=90%}

GitLab Handbook

{width=80%}

Amazon AWS S3 docs

The end

Contact info

Igor Khorlo

{ width=300px style="background:none; border:none; box-shadow:none;" }

https://www.linkedin.com/in/igor-khorlo-4546129a/

[email protected]

[email protected]

::: notes

General advise – You will have to spend some time to get used to it, but it will worth it in the end.

:::