search

nimbella / docs

Apache License 2.0
3 stars 9 forks source link

Create map of where documents should be #30

Open JamieDawson opened 3 years ago

JamieDawson commented 3 years ago

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

Introduction

Nimbella Project

Serverless SDK

CLI

Workbench

Getting Started

Developing and Deploying Serverless APIs

Developing and Deploying Web

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

Documents coming soon

JamieDawson commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

JamieDawson commented 3 years ago

@joshuaauerbachwatson , I agree with your overall post.

JamieDawson commented 3 years ago

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

JamieDawson commented 3 years ago

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