[RFC] few ideas about docs

[liuggio]

The Weave information for newcomers are pretty distributed

• Website
• Introduction, Installation and Example in the Readme
• Docs -> technical reference
• Getting Started Guides with reference to Docs
• Help and Support
• Blog
• GH issues

  Few Ideas on my mind:

I think you have a great documentation but is quite spread. Please do not take this as criticism are ideas in order to explain better the power of Weaves to newcomers.

• I really like the quick install of Scope in order to try the product, but the Net quick install is the real install and not show its power, would be great to have a simple getting started page on the website that shows the benefit one of the most common scenario like Python(or Ruby or Go or PHP)+DB with swarm/compose/machine in order to break the first step of learning curve for each product (taking content from the getting started page)
• would be great remove noise in the the first chapter of getting started enforcing the link of 2nd/3rd chapter at the end of the article
• IMHO Getting started is playing the role also of a cookbook. The cookbook is a term for tutorials explaining how to solve the most recurrent problems is for those user already understood the power of the product.
• A single documentation repository with a doc-framework like read-the-docs (or an improved Jekyll theme) will help with:
  • Docs Versioning (we can copy the elixir-lang repos it uses Jekyll and recompile every night)
  • CI on documentation, is quite common and easy to install Jekyll or the read-the-docs compilation with travis-ci on GH commit hook.
• API of the product are not so explicit

Let me know what do you think.

PS: From now to the first week of Jan I can help contributing.

[errordeveloper]

@liuggio thank you very much for these suggestions! Please let me digest this and I'll post a few comments shortly.

[errordeveloper]

These are all very good suggestions @liuggio, please see my comments below.

API of the product are not so explicit

Do you mean internal DNS and IPAM APIs?

Docs Versioning

We have this already, it's just not exposed to the user, as we don't see an explicit need for it right now.

CI on documentation

The docs from weaveworks/weave and the guides from weaveworks/guides are already built and uploaded to our website in CI.

IMHO Getting started is playing the role also of a cookbook. The cookbook is a term for tutorials explaining how to solve the most recurrent problems is for those user already understood the power of the product.

Are "cookbooks" different from "guides" in your mind?

would be great remove noise in the the first chapter of getting started enforcing the link of 2nd/3rd chapter at the end of the article

I generally agree. Some other users have said that they don't want to use Machine and prefer something that would be generalised a bit more...

I really like the quick install of Scope in order to try the product, ...

Thank you!

...but the Net quick install is the real install and not show its power, would be great to have a simple getting started page on the website that shows the benefit one of the most common scenario like Python(or Ruby or Go or PHP)+DB with swarm/compose/machine in order to break the first step of learning curve for each product (taking content from the getting started page)

Have you looked at the ones below? Would love to hear your comments on how these could be improved!

• https://github.com/weaveworks/guides/tree/master/nginx-ubuntu-simple
• https://github.com/weaveworks/guides/tree/master/rails-ubuntu-simple

PS: From now to the first week of Jan I can help contributing.

Thanks, we will happily help you out! I'd like to suggest building a little app with a framework of your choice on top of ECS. What do you think?

[liuggio]

We have this already, it's just not exposed to the user, as we don't see an explicit need for it right now.

:+1:

are already built and uploaded to our website in CI.

:+1:

Are "cookbooks" different from "guides" in your mind?

Guides and cookbooks could be the same term but, in you domain the term guide is used as 'getting started' and getting started, for me, should be a tool for a new user to understand the product in the discovery phase, and not for a particular domain.

Getting started to me should answer to 2 questions:

• is the tutorial showing the bigger benefit with an easy hands on?
• is the tutorial showing my technology at glance?

Maybe i can help on what I did the first time (I think you have tools show the funnels): I'm a developer, I found weave into the tutum node, I thought tutum has a slow dns update, I went to the http://wave.works I found different products (I thoughts wow I can have a benefit using it), I tried Scope, and I tried to understand how 'net' could be used in order to speed up my dev-life, (I still was looking something for my dns component), i read all the how it works but it didn't help finally i understood that the dns component is inside the Net :)

About:

Have you looked at the ones below? Would love to hear your comments on how these could be improved!

and

Thanks, we will happily help you out! I'd like to suggest building a little app with a framework of your choice on top of ECS. What do you think?

Those also are great guides, I love them, I think the problem is not in the content, is only how to organize them better them (maybe starting from studying the funnels and the flow :))

Those are just my impressions, I'm not proficient of your products.