docs: init docusaurus #78
Conversation
|
Going to review documentation ideas from Notion to figure out what fits in the new open source documentation strategy. Initial goal is to determine three things to tell visitors about Stochastic so they can understand the big picture value and get motivated to engage and/or learn more. Goal is to complete this by July 2nd. Edit: This will include some top level copy in the markdown, not just the list of three items. |
|
Opening up for comment and review but not ready for merge. |
docs/docs/architecture.md
Outdated
|
|
||
| At the same time, the previously mentioned smart phone revolution fundamentally changed business expectations of technology. Many services that previously relied on call-centers, store locations, agents, tellers, paper, mail and fax, became **digital touch points**. The enterprise IT department had, until this point, centralized the administration of database, infrastructure, network, and software development. It made software for people who were **paid to use it** (employees). Now it had to design, plan, and implement **customer** systems at scale for a multitude of devices and networks. | ||
|
|
||
| It is uncomfortable but necessary to remind the reader that until the agile transformation >75% of enterprise software projects were considered **failures**. Consequently, to rise in the ranks of Enterprise IT during this period one had to develop a keen sense of risk aversion and deflection of blame. Leadership decisions regularly reflected this. |
There was a problem hiding this comment.
Where does this 75% number come from?
There was a problem hiding this comment.
Really old statistic. I'd have to find the original study which I've long since forgotten.
docs/docs/architecture.md
Outdated
|
|
||
| To validate this assertion let's compare observations: | ||
|
|
||
| During the micro-computer (PC) revolution we (as an industry) moved from time-sharing of a central large computer (mainframe), to a hierarchical partitioning of compute and storage. Initially we called this "client/server", then "three tier architecture", and eventually "_n_-tier". Software and infrastructure analysis and design patterns emerged during this time period that served us well into the introduction of smart phones and the modern age. |
There was a problem hiding this comment.
Are we assuming the reader understands what three tier and n-tier means?
There was a problem hiding this comment.
This specific article will be in a sub section targeted at architects and sr. devs. So, yes, hopefully. I should link it to the terms either way.
docs/docs/architecture.md
Outdated
|
|
||
| In this journey I believe distributed systems principles, defined in the 1970's, will find a new home. If we look outside, we see evidence of their success for companies operating at scale. Distributed systems has an academic feel to it, with Stochastic we'd like to make it approachable, useful. To quote Alan Kay, _"simple things should be simple; complex things should be possible."_ | ||
|
|
||
| I believe we will also discover that "serverless" aligns with how digital business (and line of business applications) should view technology. Serverless is so well aligned with business fundamentals that I believe it will lead to the biggest change in enterprise software development since object-oriented programming. |
There was a problem hiding this comment.
Can we express how enterprise software development doesn't have to be synonymous with slow/out dated/legacy? As the cloud is maturing, businesses should be excited to ride that wave. If they start adopting serverless technology and modern tooling, not only will their products provide a better CX but perhaps they are also able to attract talent to their organization? I'm curious what these organizations use for version control and project management? I feel that the most successful organizations won't just be those who adopt serverless, but also those that adopt GitHub. Are they willing to do that? Can they transform themselves?
There was a problem hiding this comment.
Can we express how enterprise software development doesn't have to be synonymous with slow/out dated/legacy?
Yes. You have to be careful how you go about that with this audience though. You want your suggestion for change to be specific to the audience.
If they start adopting serverless technology and modern tooling, not only will their products provide a better CX but perhaps they are also able to attract talent to their organization?
Yes, perhaps. Keep in mind, in a large organization people are deeply invested in optimizing a narrow set of parameters. Whilst we should all generally care about the customer, the audience for this message is architects and Sr. Developers. A separate introduction for product managers is in order and should talk specifically about the customer benefits.
This doc was mostly stream of consciousness.
I feel that the most successful organizations won't just be those who adopt serverless, but also those that adopt GitHub. Are they willing to do that? Can they transform themselves?
Focus on solving the pains they know they have. You cannot change the entire organization in one fell swoop.
There was a problem hiding this comment.
@ryan-mars, @sam-goodwin makes a good on attraction of talent. This is a huge problem they don't and won't see unless we agitate it...
|
If nobody has any objections I'm going to merge. Next PR will be filling out more content. |
In order to begin testing our various hypotheses we need a place where people can go to learn about Stochastic, Event Storming, and building serverless distributed systems.
Work on initial documentation/content strategy should go in this pull request.
git clone [email protected]:stochastic/stochastic.gitcd stochasticgit checkout docusauruscd docsnpm installnpm servegit pullgit commit ...git push