Make it easier to find guides of how to get started and such

[PEZ]

Is your feature request related to a problem? Please describe.

I learn by doing. The current main site for Polylith, which I assume is polylith.gitbook.io, tells me the what and the why, but lacks the how. It doesn't even tell me where to find this. The closest it gets (as far as I can understand) is the videos and the Real World Example app. The latter is the closest to what I am looking for, but it is not exactly what I am looking for. I think that what I am looking for actually exists in some forms. Sometimes I have been lucky when googling and found some guides. But today I fail.

An observations I have is that the current site looks like a documentation site, so I always expect to find documentation.

Describe the solution you'd like

I want the main site to either contain these guides or make it super easy to find them. If the information doesn't fit there, the site should be more obviously a product site, I think. See https://babashka.org for an example of what I mean by this. It is clearly about the product Babashka, while also making it easy to find reference information, guides and cookbooks.

[furkan3ayraktar]

Hi @PEZ!

There are two different official Polylith sites. The first one is polylith.gitbook.io/polylith, which has content about the what, the why, and an in-depth explanations of all the concepts that make up Polylith architecture. It also contains links to other resources such as videos, presentations, the example project and the FAQ.

The second is polylith.gitbook.io/poly. This one is the documentation for Polylith's Clojure CLI. It includes sections for how to install the tool, how to update it, and also all the available commands.

Could you elaborate on what you mean by guides? Are you looking for something that walks the user through how to create a Polylith workspace from scratch and start using the CLI tool? If that is the case, the closest to that is probably the one in the realworld example project: How to create this workspace from scratch. I would like to hear more about how we can improve this and make it more visible.

If this is not what you mean, could you give some examples? What type of guides could we provide? When I looked at the babashka website, the landing page is a marketing/product page and there is the docs page which has very similar content to our two gitbook sites.

I would like to explore this topic more and make sure everyone can find good resources to get started with Polylith.

Cheers,
Furkan

[PEZ]

Low hanging fruit: Make it easy to find the Poly tool site from the Polylith site. Is there even a link anywhere? I can't find it.

I mean: Hello @furkan3ayraktar! (Where are my manners? 😄)

The How to create this workspace from scratch is exactly what I was looking for! I have sometimes found it. I think it should be moved to at least a document of its own and that the Polylith site should make it super hard to miss its existence.

Your answers/questions also confuse me since they seem to blur the line between Polylith and the tool. In my mind, so far, Polylith is more the structure, concept, mindset. The tool helps me with common tasks when following the Polylith path.

I think there are several layers to this, and I am not clear in my own head about which they are. Let's explore the problem before we jump on any of my suggestions.

I struggle to understand what Polylith is. I get excited hearing you three talk about it. I sense that it is great. That the creators of Polylith have invented something pretty awesome. Or found it, in the broad daylight where it was hidden, maybe? But I have yet to really grasp it. This even though I am using it. I am using it in a smallish project that I only work with once a month. And I also find myself smitted by some of the Polylith concepts in a way that make me transform other projects I work with in the general direction of Polylith. So... maybe I have understood something, but am still waiting for things to click enough to be able to articulate it and describe it to others. Also, I have hardly used the tool at all so far.

Even though the Polylith site says it is high level. It also seems to be a whitepaper. I think I need something more ”at a glance” to get help understanding what Polylith brings to the table, what problems I might have that Polylith can help me with, and how it helps me with these problems or challenges or opportunities.

I have a feeling the Polylith site has the information I need. At least that putting together all the material that the team has produced so far, the information is there. But I get frustrated trying to find what I am looking for. (Partially I don't know what I am looking for so maybe there is only so much you can do about it).

Maybe we can dig this tunnel from two ends?

1. Figuring out who our target audiences are and what questions they arrive with, and go from there to wireframing some ideas on how to make it easy for each one of them to get find their answers.
2. Make an inventory of the material we have that we can surface in the ways we figure out in 1. And also see the gaps we might need to cover with new material.

I hope I am making at least some sense. 😄 ❤️

[tengstrand]

Hi Peter / @PEZ !

I'm sure there are several other people struggling with finding how to start with Polylith, so this feedback is very valuable to us!

The documentation of the poly tool covers all the commands included by the tool by walking you through an example, and it starts by creating the example workspace which also includes a link to the end result which is a command line tool that calls a remote service and prints out "Hello Lisa" (if you pass in "Lisa" as an argument).

The purpose of the example app is mainly to teach the use in how to use the poly tool itself (the Clojure version) but it's also a good way to get a deeper understanding of the different concepts in Polylith: interface, component, base, project and workspace, and how they work out in practice.

[furkan3ayraktar]

I think you are making more than some sense @PEZ 😄. I was also reluctant about moving the CLI tool documentation from GitHub to GitBook, although @tengstrand convinced me that it was more searchable and more structured in GitBook, also better looking.

Now, I understand what you meant with the babashka website as well. A landing page that we can clearly link to different parts of the documentation and other places based on what potential visitors look for.

[tengstrand]

No one would be happier than me if we could nail how to describe Polylith so that everyone (or at least people that could benefit from it) would understand!

Maybe we should form a group with people that are new to Polylith and also people that have worked with it for a while, to get feedback and ideas about how to improve and/or restructure the current documentation.

[PEZ]

Sounds excellent, @tengstrand!

[lsh-0]

I'm going to hang a comment off of this ticket because I'm having issues with the Gitbook style of documentation as well.

I recently opened a ticket with what I felt to be a reasonable albeit a little embarrassing question (just what is a brick?) given how far into the docs I had read and how much code I had already generated. I closed it almost immediately as I didn't want to waste anyone's time, but after more frustrations getting to the bottom of what is going on with the testing features in polylith and no further elucidation of what a 'brick' is I resorted to searching reddit for any glimmer of insight and found a link to documentation that I guess has been moved to Gitbook form: https://github.com/polyfy/polylith/tree/v0.2.12-alpha

In just a few moments I had an answer to my question and what looks to be a fairly complete set of docs I can grep over.

I'm only voicing my opinion and not offering any solutions, but the Gitbook/paginated style of documentation and the two distinct sets of documentation (polylith and poly tool) do more than just frustrate me: they make me ask basic questions, feel like a fool, waste people's time and second guess my decision around trying polylith.

[tengstrand]

Hi guys!

I've tried to address a number of issues in the documentation:

The introduction in the high-level documentation in the second sentence says "There are several ways of learning Polylith" followed by these sections:

• Try it out yourself
• Look at working code
• Watch a video
• Listen to a podcast
• Slack
• Read a blog post
• Production systems
• Read the documentation

The purpose of the new structure is to give the reader an overview of all the different types of resources, so they can choose what they prefer (people learn in different ways).

If you are a Clojure developer and want to start coding, the "Try it out yourself" section is what hits you first, which should be an improvement over before.

When we introduce the words component and base on this first page, we also show "(brick)" to give the alternative name.

On the next section, Polylith in a nutshell, brick has its own section:

I think that having a single document combined with a fixed left menu that allows us to quickly navigate between sections and also search for the content using the built in search support in the browser (instead of using the built in search functionality in Gitbook) may be an improvement. If we could find a better alternative, then that could be an option.

Please give your feedback @PEZ and @lsh-0.

/Joakim

[lsh-0]

Documentation is a notoriously slippery problem alright and no solution is going to please everybody. I am grateful for this though:

So, thank you ;)

I think that having a single document combined with a fixed left menu that allows us to quickly navigate between sections and also search for the content using the built in search support in the browser (instead of using the built in search functionality in Gitbook) may be an improvement.

I agree, but I often feel like I'm being old fashioned and unreasonable. So long as whatever you come up with is fairly plain, doesn't break with javascript turned off, doesn't hijack browser shortcuts etc. I have to deal with this site daily and it would be hard to do any worse.

Thanks again for your work.

[tengstrand]

Okay, cool!

[tengstrand]

I will close this now.