Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Revamp #496

Merged
merged 14 commits into from
Feb 28, 2018
Merged

Documentation Revamp #496

merged 14 commits into from
Feb 28, 2018

Conversation

vishal-biyani
Copy link
Member

@vishal-biyani vishal-biyani commented Feb 13, 2018

Adding documentation as per new structure and details


This change is Reviewable

@vishal-biyani vishal-biyani added this to the 0.6.0 milestone Feb 13, 2018
@vishal-biyani vishal-biyani added the documentation All issues related to docs repo: https://github.com/fission/docs.fission.io label Feb 13, 2018
@soamvasani
Copy link
Member

Thanks @vishal-biyani. Would you mind putting the structure in the PR description too?

@life1347 @timirahj please take a look and comment if you have any ideas/suggestions around the doc structure.

@vishal-biyani
Copy link
Member Author

Below structure and basic content are targeted as part of this PR.
Some areas might be kept in the draft based on content amount/maturity etc.
Requesting your comments on structure:

.
├── Introduction (Homepage describing basics)
├── Contributing
│   └── Compilation Fission
│   └── Testing Debugging & known issues
├── Installation
│   └── Quick Installation
│   └── Pre-requisites
│   └── Minikube Installation
│   └── Hosted Kubernetes Cluster
│   └── First example
│   └── Limitations and known issues
│   └── Upgrading from older versions
│       └── UPGRADING FROM V0.1 TO V0.2.X
│       └── UPGRADING FROM V0.3 TO V0.4.X
│       └── UPGRADING FROM V0.4 TO V0.5.X
├── Fission Concepts
│   ├── Functions
│   ├── Environments
│       └── Creating custom environments
│   └── Executors 
│   └── Triggers
│       └── Time triggers
│       └── Http Triggers
│       └── MQ Triggers
│   ├── Watches
│   └── Package
├── Using fissoon
│   ├── Functions
│   ├── Environments
│       └── Creating custom environments
│   └── Executor Types
│       └── PoolManager
│       └── NewDeploy
│   └── Triggers
│       └── Time triggers
│       └── Http Triggers
│       └── MQ Triggers
│   ├── Watches
│   └── Package
├── Fission Workflows
│   └── Details of Workflow (To be further expanded)
└── Resources
    └── Links etc.

@@ -0,0 +1,6 @@
---
title: "Executor"
date: 2017-09-07T20:10:05-07:00
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Date seems to be off in many of the documents, I would propose to just set it to today.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I am not sure if Hugo has a better way, adding TS manually seems odd to me

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah okay, I was not aware this was generated by Hugo. It seems to be just a ISO 8601 datetime, so probably your editor has an option to insert the current datetime, if it is needed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Date doesn't really matter. We're not displaying it. You could probably remove it.

Copy link
Member

@erwinvaneyk erwinvaneyk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was not sure how much more you are planning to add, so I just left a couple of comments rather than a full review

date: 2017-09-07T20:10:05-07:00
draft: false
weight: 50
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As a starting point, you could just copy and paste the contributing.md that we have in the root

@vishal-biyani
Copy link
Member Author

@erwinvaneyk - yes still WIP and will add another batch tomorrow for review.

@erwinvaneyk
Copy link
Member

Ok understood, @vishal-biyani :) It might be an idea to have a "wip" label for these kinds of PRs

@vishal-biyani vishal-biyani changed the title Documentation Revamp [WIP] Documentation Revamp Feb 13, 2018
@@ -0,0 +1,6 @@
---
title: "Watch"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest removing this; a watch isn't really a separate concept, but just a type of trigger.

@@ -1,181 +1,6 @@
---
title: "Installation Guide"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What's wrong with "guide"?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am sorry, I have too many coding tendencies while also typing normal text :) and I like camel case 😈

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, I didn't mean the casing of the word guide/Guide. I meant, the diff removes the word guide and changes "Installation Guide" to just "Installation", and I was wondering why you did that.

date: 2017-09-07T20:10:05-07:00
draft: false
weight: 20
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So I think I disagree with this idea... I really dislike jumping around 3 different pages while trying to install something. I feel like the all-in-one page is better for new users. Thoughts?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On second thoughts, I agree. It is not friendly to have jump n number of pages to install something. Will put in a single one.

date: 2017-09-07T20:10:05-07:00
draft: false
weight: 26
---
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Kinda vague... remove unless we have something to populate this with

@@ -1,7 +1,8 @@
---
title: "Kubernetes Quick Install"
title: "Quick Installation"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, this is actually a Kubernetes install, not Fission install

@@ -0,0 +1,6 @@
---
title: "Environemnt"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo (spelling)

@@ -0,0 +1,6 @@
---
title: "Executor"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't really write a usage guide to the executor; it's a component of our implementation. We should write a usage guide to controlling function execution, latency, throughput, memory costs etc.

@@ -0,0 +1,6 @@
---
title: "Watch"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above, watches are just a type of trigger

@@ -0,0 +1,25 @@
---
title: "Environemnt"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

typo

@@ -0,0 +1,6 @@
---
title: "Executor"
date: 2017-09-07T20:10:05-07:00
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Date doesn't really matter. We're not displaying it. You could probably remove it.

@vishal-biyani vishal-biyani changed the title [WIP] Documentation Revamp Documentation Revamp Feb 19, 2018

# Fission Concepts

#### Understanding Fission terminology and concepts
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a link, right?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No, this is a chapter title and subtitle, for each chapter, it shows up like this:
image

And the chapter has subpages - which user can click on and walk through each topic:
image

| Python 3 | `fission/python-env` |
| Ruby | `fission/ruby-env` |

To create custom environments you can extend above or create your own environment from scratch.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

you can extend one of the environments in the list, or create...


# Contributing to Fission

### Development guide
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

link


### Installing and upgrading Fission
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

link


# Using Fission

### Examples, code samples and How To's
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does this show up? Also, suggest rephrasing to "Usage guides, tutorials and examples".

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So this is a "chapter" title and it shows up like this:
image

@@ -1,8 +1,11 @@
---
title: "Access secret/configmap in function"
title: "Secret/configmap in function"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I liked the previous title better (though "Accessing secrets..." is better than "Access secret...")

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I think I shortened it because it was not looking good, most of the titles are short and this is much longer than others. For now, I changed it back, but I want to get back to aesthetics of this later :)
image


### Create an environment

You can create an environment from node-env image and specify the resources such as memory and CPU along with poolsize. The poolsize controls how many warm pods are created initially.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"You can create an environment on your cluster from an image for that language. Optionally, you can specify CPU and memory resource limits. You can also specify the number of initially pre-warmed pods, which is called the poolsize."

When you create an environment, you can specify a builder image and builder command which will be used for building from source code. You can override the build command when creating a function. For more details on builder and packages you should check out examples in [Functions](../functions) and [packages](../package)

```
fission env create --name python --image gcr.io/fission-ci/python-env:test --builder gcr.io/fission-ci/python-env-builder:test
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We shouldn't be telling people to use our test builds... this guide should point at released images only.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, I had not found official builder image when I wrote this, fixed now.

weight: 43
---

### Pool executor, low latency
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In this usage guide we shouldn't talk about the executor in the subheadings, only the use case. E.g.

"Functions with no cold start overhead"
"Functions with no idle cost"
"Autoscaling"

@@ -0,0 +1,130 @@
---
title: "Package"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needs a better title

@vishal-biyani
Copy link
Member Author

Also addresses #470


Newdeploy executortype can be used for requests with no particular low-latency requirements, such as those invoked asynchronously, minscale can be set to zero. In this case the Kubernetes deployment and other objects will be created on first invocation of the function. Subsequent requests can be served by the same deployment. If there are no requests for certain duration then the idle objects are cleaned up. This mechanism ensures resource consumption only on demand and is a good fit for asynchronous requests.

For requests where latency requirements are stringent, a minscale greater than zero can beset. This essentially keeps a minscale number of pods ready when you create a function. When the function is invoked, there is no delay since the pod does not have to created. Also minscale ensures that the pods are not cleaned up even if the function is idle. This is great for functions where lower latency is more important than saving resource consumption when functions are idle.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a minscale greater than zero can be set

@life1347
Copy link
Member

Review status: 0 of 25 files reviewed at latest revision, 27 unresolved discussions.


Documentation/docs-site/content/concepts/executor.en.md, line 25 at r8 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

a minscale greater than zero can be set

there is no delay since the pod does not have to be created...?


Documentation/docs-site/content/concepts/executor.en.md, line 29 at r9 (raw file):

### The latency vs. idle-cost tradeoff

The executors allow you as a user to decide between latency and a small idle cost tradeoff. Depending on the need you can choose one of the combinations which is optimal for your use case. In future a more intelligent mechanism dispatch mechanism will enable more complex combinations of executors.

In future, a more intelligent dispatch mechanism ...


Documentation/docs-site/content/concepts/executor.en.md, line 39 at r9 (raw file):

### Autoscaling

The new deployment based executor provides autoscaling for functions based on CPU currently. You can set the intial and maximum CPU for a function and target CPU at which autoscaling will be trigerred. Autoscaling is useful for workloads where you expect intermittant spikes in workloads. It also enables optimal usage of resources to execute functions, by using a baseline capacity with minimum scale and ability to burst upto maximum scale based on spikes in demand.

based on CPU usage ...
burst up to ....


Documentation/docs-site/content/concepts/functions.en.md, line 6 at r9 (raw file):

weight: 31
---
A function is piece of code that will be invoked based on a [trigger](../trigger). The code follows the Fission interface. In practice the function is only an entry point for execution and it can be backed by a larger program or module.

is a piece of...
In practice, the function...


Documentation/docs-site/content/concepts/trigger.en.md, line 15 at r9 (raw file):

## Time Trigger

If you want a function to be called at a periodic frequency then the time triggers are perfect for the use case. Time trigger follow cron like specifications and are invoked based on the cron schedule.

Time triggers follow


Documentation/docs-site/content/concepts/trigger.en.md, line 17 at r9 (raw file):

If you want a function to be called at a periodic frequency then the time triggers are perfect for the use case. Time trigger follow cron like specifications and are invoked based on the cron schedule.

Time trigger bases invocations are great for running scheduled jobs, periodic cleanup jobs, periodic polling based invocations etc. 

Time trigger based ...


Documentation/docs-site/content/concepts/trigger.en.md, line 21 at r9 (raw file):

send a reponse
send a response

the message in queue
the messages in queue

Currently nats-streaming and azure-storage-queue are supported message queues supported.
Currently, nats-streaming and azure-storage-queue are supported.


Comments from Reviewable

@vishal-biyani
Copy link
Member Author

Review status: 0 of 25 files reviewed at latest revision, 27 unresolved discussions.


Documentation/docs-site/content/concepts/_index.en.md, line 10 at r5 (raw file):

Previously, vishal-biyani (Vishal) wrote…

No, this is a chapter title and subtitle, for each chapter, it shows up like this:
image

And the chapter has subpages - which user can click on and walk through each topic:
image

Done.


Documentation/docs-site/content/concepts/environments.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

typo

Done.


Documentation/docs-site/content/concepts/environments.en.md, line 24 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

you can extend one of the environments in the list, or create...

Done.


Documentation/docs-site/content/concepts/executor.en.md, line 3 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Date doesn't really matter. We're not displaying it. You could probably remove it.

Done.


Documentation/docs-site/content/concepts/executor.en.md, line 25 at r8 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

there is no delay since the pod does not have to be created...?

Done.


Documentation/docs-site/content/concepts/executor.en.md, line 29 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

In future, a more intelligent dispatch mechanism ...

Done.


Documentation/docs-site/content/concepts/executor.en.md, line 39 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

based on CPU usage ...
burst up to ....

Done.


Documentation/docs-site/content/concepts/functions.en.md, line 6 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

is a piece of...
In practice, the function...

Done.


Documentation/docs-site/content/concepts/trigger.en.md, line 15 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

Time triggers follow

Done.


Documentation/docs-site/content/concepts/trigger.en.md, line 17 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

Time trigger based ...

Done.


Documentation/docs-site/content/concepts/trigger.en.md, line 21 at r9 (raw file):

Previously, life1347 (Ta-Ching Chen) wrote…

send a reponse
send a response

the message in queue
the messages in queue

Currently nats-streaming and azure-storage-queue are supported message queues supported.
Currently, nats-streaming and azure-storage-queue are supported.

Done.


Documentation/docs-site/content/contributing/_index.en.md, line 6 at r1 (raw file):

Previously, erwinvaneyk (Erwin van Eyk) wrote…

As a starting point, you could just copy and paste the contributing.md that we have in the root

Done.


Documentation/docs-site/content/contributing/_index.en.md, line 10 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

link

Done.


Documentation/docs-site/content/installation/_index.en.md, line 10 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

link

Done.


Documentation/docs-site/content/installation/kubernetessetup.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Hmm, this is actually a Kubernetes install, not Fission install

Done.


Documentation/docs-site/content/usage/_index.en.md, line 10 at r5 (raw file):

Previously, vishal-biyani (Vishal) wrote…

So this is a "chapter" title and it shows up like this:
image

Done.


Documentation/docs-site/content/usage/access-secret-cfgmap-in-function.md, line 2 at r5 (raw file):

Previously, vishal-biyani (Vishal) wrote…

Yeah, I think I shortened it because it was not looking good, most of the titles are short and this is much longer than others. For now, I changed it back, but I want to get back to aesthetics of this later :)
image

Done.


Documentation/docs-site/content/usage/environments.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

typo (spelling)

Done.


Documentation/docs-site/content/usage/environments.en.md, line 9 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

"You can create an environment on your cluster from an image for that language. Optionally, you can specify CPU and memory resource limits. You can also specify the number of initially pre-warmed pods, which is called the poolsize."

Done.


Documentation/docs-site/content/usage/environments.en.md, line 22 at r5 (raw file):

Previously, vishal-biyani (Vishal) wrote…

Yes, I had not found official builder image when I wrote this, fixed now.

Done.


Documentation/docs-site/content/usage/executor.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

We shouldn't really write a usage guide to the executor; it's a component of our implementation. We should write a usage guide to controlling function execution, latency, throughput, memory costs etc.

Done.


Documentation/docs-site/content/usage/executor.en.md, line 7 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

In this usage guide we shouldn't talk about the executor in the subheadings, only the use case. E.g.

"Functions with no cold start overhead"
"Functions with no idle cost"
"Autoscaling"

Done.


Documentation/docs-site/content/usage/package.en.md, line 2 at r5 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Needs a better title

Done.


Documentation/docs-site/content/concepts/watch.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Suggest removing this; a watch isn't really a separate concept, but just a type of trigger.

Done.


Documentation/docs-site/content/installation/known-issues.en.md, line 6 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Kinda vague... remove unless we have something to populate this with

Done.


Documentation/docs-site/content/resources/_index.en.md, line 1 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Right, but I'm concerned that it will become disorganized. The blog has it's own site. I suggest removing this section.

Done.


Documentation/docs-site/content/usage/watch.en.md, line 2 at r1 (raw file):

Previously, soamvasani (Soam Vasani) wrote…

Same comment as above, watches are just a type of trigger

Done.


Comments from Reviewable

@soamvasani
Copy link
Member

Just a few comments, then good to merge --


Reviewed 7 of 39 files at r1, 4 of 17 files at r3, 4 of 22 files at r4, 7 of 11 files at r5, 7 of 8 files at r6, 5 of 6 files at r7, 3 of 3 files at r8, 3 of 3 files at r10.
Review status: all files reviewed at latest revision, 15 unresolved discussions.


Documentation/docs-site/content/concepts/package.en.md, line 7 at r10 (raw file):

---

Most real world applications are more than a single file of code and typically have dependencies on libraries etc. Packages in fission solve three distinct problems:

This doc needs to specifically define both archives and packages.

But, later. Let's merge this and improve it iteratively.


Documentation/docs-site/content/usage/access-secret-cfgmap-in-function.md, line 6 at r10 (raw file):

weight: 47
---
<!--

Can you please remove this comment and file an issue listing out the specific things in this doc that you think should be changed?


Documentation/docs-site/content/usage/trigger.en.md, line 2 at r10 (raw file):

---
title: "Trigger"

This is missing K8s watch triggers.

(Add it later, no need to block this)


Comments from Reviewable

@vishal-biyani
Copy link
Member Author

Updated #499 for changes to cover later and addressed one comment.

@vishal-biyani vishal-biyani merged commit 1b1c4f1 into master Feb 28, 2018
@vishal-biyani vishal-biyani deleted the documentation_spurt branch February 28, 2018 06:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation All issues related to docs repo: https://github.com/fission/docs.fission.io
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants