src-d/engine-deprecated

Enhance gitbook docs

Opened this issue · 5 comments

dpordomingo commented

I'd like to apply same enhancements that done in source{d} Lookout, and also aligned with our current guidelines:

  • smaller README, with its tree biggest parts moved to its dedicate doc
    • quickstart is huge, and we even explain how to install docker (?), move to quickstart.md
    • move examples to examples.md
    • we also explain what bblfsh is, move it ro bblfsh.md
  • same docs structure than in lookout
  • proper CONTRIBUTING, NOTICE and such.

since we already have the contents, it should be easy and fast to do the changes.

(PS)

My suggestion was to achieve something like this https://dpordomingo.gitbook.io/engine
Maybe adding a couple of queries to show off, but focusing on being direct, concise and clear.

dpordomingo commented

My suggestion was to achieve something like this https://dpordomingo.gitbook.io/engine
Maybe adding a couple of queries to show off, but focusing on being direct, concise and clear.

carlosms commented

My question to @marnovo is which one these two points of view do we want to apply on the readme

  • overview and showcase of what is engine, what it takes to install and get it running, and what it can do. Oriented to newcomers, acts as a landing page.
  • index of reference documentation. Oriented to people that already installed engine and come back for the docs.

I see what we have now, a big readme that contains everything in the first case. And @dpordomingo's suggestion fitting with the second case.
Personally I'm ok with both, but I'd prefer to have Product's input before making changes.

dpordomingo commented

I don't see why the README.md I suggested would is...

[...] oriented to people that already installed Engine and come back for the docs

The quickstart section is in the very top, and links to the complete instructions about how to install it.

And about the convenience of considering our README.md as "a landing page", I'm not sure what "landing" stands for. What I understood is that https://sourced.tech/engine is the product landing, and https://docs.sourced.tech/engine its docs.

carlosms commented

I don't see why the README.md I suggested would is...

[...] oriented to people that already installed Engine and come back for the docs

The quickstart section is in the very top, and links to the complete instructions about how to install it.

Then scratch oriented and call it optimized. It is optimized for people that already installed and can easily skip the quickstart.

And about the convenience of considering our README.md as "a landing page", I'm not sure what "landing" stands for. What I understood is that https://sourced.tech/engine is the product landing, and https://docs.sourced.tech/engine its docs.

Then scratch landing and call it the welcome screen of the github repo page. I mean the readme is rendered in the main github repo page, and we may want to optimize it for different points of view.

I'm not attacking your proposal, all I'm saying is that having things organized in sub sections has some advantages, and having everything showcased in a single page has other advantages.

dpordomingo commented

I know you're not attacking any proposal, but trying to define better both approaches, in order to see which one fits our necessities better. 😁 And that's a great approach!!!

What happens is that I'm not sure that arranging the docs in smaller sections, with a clean and concise README is more oriented to people that already knows/installed Engine.
I'd say that such README, —as it was also described in our conventions—, is more valuable for both: newcomers and experienced users.

But for sure, I'm opened to new points of view. 😊