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

Create map of where documents should be #30

Open
JamieDawson opened this issue Dec 30, 2020 · 6 comments
Open

Create map of where documents should be #30

JamieDawson opened this issue Dec 30, 2020 · 6 comments

Comments

@JamieDawson
Copy link
Contributor

JamieDawson commented Dec 30, 2020

Update: Here is the current layout of the docs we have. We can write down document recommendations by adding them to the list.

Introduction

  • Welcome
  • NImbella account

Nimbella Project

  • Deployer Overview
  • Project
  • Namespace
  • Actions
  • Project Configuration
  • Deployer Feature
  • Single Action Example
  • Tieing Namespaces to Projects

Serverless SDK

  • Nimbella File Stores

CLI

  • Install CLI
  • Nim Commands
  • Command Flags
  • Nim Command Summary
  • Nim VS WSK

Workbench

  • Workbench
  • Access the Nimbella Workbench
  • Workbench - Deploy from GitHub
  • Workbench - Playground Intro
  • Workbench - Playground Exports

Getting Started

  • Building
  • Creating your project

Developing and Deploying Serverless APIs

  • Sample project walkthrough
  • Basic KV Commands
  • Deploy from GitHub

Developing and Deploying Web

  • Web Content

-----------------------------------------------------------

Documents coming soon

  • Project Limits (Jamie)
@JamieDawson
Copy link
Contributor Author

Hey @joshuaauerbachwatson, this is where I'm now putting my layout for the document structure.

What we should do is come up with a good structure for the documents and layout a general idea of what file topics should go in what order. If you have any suggestions for files and topics that should be added or rearranged, please let me know.

Also, per our last discussion. I think one of the hardest things we'll have to do after coming up with a good project structure is having to re-organize the written content. This of course is assuming we want every file to have the structure of "1)concept, 2)how-to 3)reference".

@joshuaauerbachwatson
Copy link
Contributor

I don't agree that individual documents need to conform to the three-part structure. I would not want to see. much effort expended in that direction. I think the very short term effort should be to connect what we have to some kind of top level structure without requiring much additional work beyond perhaps some further breakup of individual documents. I don't object to the structure you've laid out as part of that short term goal.

What we do after that involves some decisions about both document classification and document structure that I don't regard as final yet. In the meeting, I proposed a classification of documents into conceptual ones
like this:

https://cloud.google.com/compute/docs/load-balancing-and-autoscaling

and "how-to" ones like this:

https://cloud.google.com/iap/docs/load-balancer-howto

and reference ones like this

https://cloud.google.com/sdk/gcloud/reference

We then looked at some of our documents and said, gee, they seem to have more than one of these things in them. Sometimes all three. Well, yuh. Because, they are immature. We wrote them while trying to get prose laid down and each of the three aspects (concepts, how-tos, and reference) was sketchy enough that we combined them. I regard that as highly temporary. It's ok for our very first foray into the new offering. It's not a good structure to be made into a template for the future.

I am sure you don't think of google cloud as a good model for a documentation set (you have something else in mind). I agree it's 10 or 20 times larger (at least) than ours will ever be). But, this classification of documents by distinct purpose is important for a documentation set that is going to keep on getting used. If all we have is a good sequence for brand new users to follow, they will sign up, fool with a few demos, try out some idea that is not too different from what they've seen examples of, and then start trying to do something serious. Only users who succeed in doing something serious will stay with us. To avoid the "cliff" that occurs in many documentation sets when you get to the end of the "on ramp" documents and want to do something serious, we have to have good reference documents that facilitate easy lookup, good how-to documents covering lots of use cases that we've observed (this will grow slowly but it has to grow) and good conceptual documents for users who (e.g.) didn't think they needed an object store but now realize that they do. Users will re-enter the document set over and over again (if we succeed).

None of this says that you should not indeed go ahead and connect up what we have to a reasonable structure like what you outlined. Just let's please not make a premature decision that imposes structure on every future document that gets written which I am 100% sure is in the wrong direction (even if you disagree and Rodric disagrees, let's please continue the debate a bit longer ... there is no reason why we have to decide that level of detail now).

@rabbah
Copy link
Contributor

rabbah commented Jan 2, 2021

I concur Josh. Let’s focus on the goal of getting version out next week with what we have, and continue to iterate.

@JamieDawson
Copy link
Contributor Author

@joshuaauerbachwatson , I agree with your overall post.

@JamieDawson
Copy link
Contributor Author

I've updated the list so that we can see the documents we have in order + the documents that are pending.

@JamieDawson
Copy link
Contributor Author

This week, I plan on going over the docs and seeing if there are ways to improve them and what docs we should create.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants