search

socon-dev / socon

Socon is a microservice architecture framework that helps you focussing on deploying/chaining individual commands and custom services between your different projects
BSD 3-Clause "New" or "Revised" License
26 stars 3 forks source link

Rework README #24

Open StephaneCapponi opened 1 year ago

StephaneCapponi commented 1 year ago

The concept of Socon does not seems to be fully understand when people read the README. The example is too fictional and people can't relate to real word issue.

The concept of the framework and what issue it solved needs to be clearer.

One comment from reddit:

The actual issue that hjmb is pointing out is that your README and your documentation doesn't do an ideal job selling your project, for the lack of a better word.

Yes, the content is all there and it's quite comprehensive, like hjmb said.

But the issue that your project addresses isn't necessarily on people's mind, they probably haven't even realized they have it.

So, you need to put front and center what that issue is and how your project addresses it, with a realistic example, not fictional rockets. ...

JRbemt commented 1 year ago

I agree, I think this project has much more potential than is currently communicated through the README. Maybe rephrasing it as a microservice architecture framework, and focussing on deploying/chaining individual commands would be a an idea!? (e.g. retrieving data from different databases [projectconfigs] and manipulate that with a basecommand and maybe finally plot some results to get data insights)

Additionally I think some example projects are also needed.

StephaneCapponi commented 1 year ago

@JRbemt Yes you are right. I like the idea of microservice architecture.

This is a good example: (e.g. retrieving data from different databases [projectconfigs] and manipulate that with a basecommand and maybe finally plot some results to get data insights)

Let me give you some context on why I have created this repos and the README that way. I'm a Test and Validation engineer and I run a continuous integration system using Bamboo/Jenkins on mulitple projects. Each project is a different embedded platform. For each platform I have to build and flash similar binary with different configuration to test the stack develop by people. We are currently using mulitple shell scripts to run the CI and it's a mess. Genericity is bad and we have mulitple scripts for different projects that are copy/paste with just couple of lines that are different.

In my spare time I have decided to create that framework to make my life easier. At first I wanted the framework to be embedded oriented but then I told myself that it can be used for anything and by anyone if I make it generic enough.

Today, I really believe that this framework can be usefull for a lot of people but my ideas and the README are maybe to oriented to the problem I had. Having a different view on the project is really important for me and I'm glad you like the project and you want to contribute.

The goal is to widely share that framework. But the README is the first thing that people see and it's the priority. If you are ok, we need to work on that together and come with something great ?

StephaneCapponi commented 1 year ago

@JRbemt, I was out for couple of days. Would you like us to start a thread on what we should change in the readme if you are still iinterested, I would like to publish Socon 0.2 with this new readme and then start on the features for the 0.3. WDYT ?

JRbemt commented 1 year ago

Hey @StephaneCapponi, sounds good! I'm a bit swamped with work at the moment, but I will make some time. I think the main thing the README at the moment is missing is purpose. Interesting to hear though how you designed it for CI for different embedded platforms!! Did you ever use the framework in your work already?

StephaneCapponi commented 1 year ago

Hi, @JRbemt no problem I'm not in a hurry :) I will try to work on something on my side and find a purpose as you said. And yes I'm trying to find time at work to implement the framework!

StephaneCapponi commented 1 year ago

Hi @JRbemt, I have started the implementation of the framework at work and I'm creating new features and reporting bug in documentation or in the code. I saw that you have self-assigned this ticket to you. I really like the approach of saying that Socon is a Microservice framework. Something like:

Socon is a microservice architecture framework the helps you focussing on deploying/chaining individual commands between your different projects. Socon's create a generic Django like project structure. It's a structure that contains all the element for you to get started.

I think it would be best that we remove the "Why" section and focus more on mulitple but simple example. Also I was wondering that if we call socon a microservice framework that all "project" should be "service". WDYT ?