Missing overview of basic characteristics and features

[kravemir]

I'm searching for SSG for documentation of my project...

And, this project's "welcome" page doesn't impress me at all. Normally, I skip such projects immediately, but I see you've gone through effort to write lots of docs,... So, at least I'll give you hint, how to make it more "welcoming",... Both github project's README.md and http://cobalt-org.github.io/ are missing overview of the most important usage characteristics.

Adding a simple list of characteristic features, like:

• written in Rust for speed and safety,
• install via cargo and packaged in various distributions,
• markup language: Markdown (can be combined with custom HTML),
• uses Liquid template engine,
• ... N/A ...

Also, stick to simple list, with simple short text pointing to docs with more information. Also, you might add opinion to facts, ie. "written in Rust" is fact, and for safety and speed is (potentially true) opinion. But, facts are important.

Knowing capabilities and features of project is crucial in making decision, whether to pick some software or not. Make potential users know, what the project offers :-)

[epage]

Yeah, the README is pretty weak. First, I normally focus those towards developers and I also didn't want to duplicate a lot of stuff in the site.

And honestly, I've just not gotten to spending much time on the "marketing" side of this project.

Knowing capabilities and features of project is crucial in making decision, whether to pick some software or not. Make potential users know, what the project offers :-)

So it seems you are more interested in features than the high level marketing points. I would like to have both with either a section below the fold that goes into more detail or hover over the marketing point.

One of the big challenges is I'm not a designer or web developer. I know these things are possible but wouldn't know how to do it well. I've been hoping for contributors to help out in this regard.

written in Rust for speed and safety,

People have different opinions on whether Rust is a defining characteristic.

The sub bullets are more defining characteristics for which Rust can be listed as a contributing factor but isn't sufficient on its own.

Safety is of limited use in a SSG because it isn't exposed on the web and it is short-lived so it can be retried on crash

Performance can be a defining characteristic but I don't want to be yet another project that advertises performance without backing it up with data. Oh look, I already have a section on "Fast" which bothers me for making a claim without backing it up.; again, not focused much on marketing atm.

install via cargo and packaged in various distributions,

This isn't a defining characteristic. Are you more thinking of the idea that the quick start page should be merged into the landing page?

I think what I'd prefer is the "easy" section would show an example of getting up and running with a link to the quick start.

markup language: Markdown (can be combined with custom HTML),

Markdown could be a reasonable thing to call out in a more detailed section.

uses Liquid template engine,

I'm unsure how much of a marketing point this is but in the details for one of the sections, listing out the use of templating, powered by Liquid, would be reasonable.

And, this project's "welcome" page doesn't impress me at all. Normally, I skip such projects immediately, but I see you've gone through effort to write lots of docs,... So, at least I'll give you hint, how to make it more "welcoming",...

btw for an American audience, this can come across as extremely condescending.

[kravemir]

And honestly, I've just not gotten to spending much time on the "marketing" side of this project.

That's common among developers, and it's fine as long it's a product which has a single deployment, at one customer... However, when project is intended to be used by others (besides author's own use-case), then it's good to "sum up box's contents".

So it seems you are more interested in features than the high level marketing points. I would like to have both with either a section below the fold that goes into more detail or hover over the marketing point.

Correct. I just want to know what's in the box, without need to dig into the manual,...

The sub bullets are more defining characteristics for which Rust can be listed as a contributing factor but isn't sufficient on its own.

Probably true. As long as it's used as a standalone tool, then implementation language doesn't matter. But, features and supported standards (languages - Markdown, CSS,...) matter.

Safety is of limited use in a SSG because it isn't exposed on the web and it is short-lived so it can be retried on crash

I meant more like memory safety. I had encountered bug, where I wondered how the value got somewhere,... and, it was overflow or dangling pointers,... hard to trace, bad for developers. However, doesn't matter for end-user.

install via cargo and packaged in various distributions,

This isn't a defining characteristic. Are you more thinking of the idea that the quick start page should be merged into the landing page?

Good idea to have a quick start. Some projects are very cumberstone to setup, and short quick start means quick setup. Also, to not mix quick-start (numbered) list with features (bullet) list.

Markdown could be a reasonable thing to call out in a more detailed section.

What do you mean by that?

uses Liquid template engine,

I'm unsure how much of a marketing point this is but in the details for one of the sections, listing out the use of templating, powered by Liquid, would be reasonable.

Actually, it is a feature, and characteristics, which defines how much pain, or comfort, there is for an end-user,.. Languages have pretty much big impact, and often are crucial factor in making decision.

And, this project's "welcome" page doesn't impress me at all. Normally, I skip such projects immediately, but I see you've gone through effort to write lots of docs,... So, at least I'll give you hint, how to make it more "welcoming",...

btw for an American audience, this can come across as extremely condescending.

Sorry, I have expressed myself bad way,... Thanks for feedback. I meant, that I like when people put effort into (this) open-source projects, but it's needed to work on "box's packaging". Packaging doesn't have to be fancy, but should express important characteristics (features) for end-user.

[Geobert]

@kravemir is that better?

[kravemir]

@kravemir is that better?

Much better. At first skim of the page, "collections, tagging, categories" had hit my eyes in positive way, and even if I don't know (yet) details about them in cobalt, they look like cobalt provides useful features. Also "liquid and markdown" had hit my eyes. So, much better first impression.

I was using different static site generator. And, "simple"/"easy"/"fast" are characteristics for the developers. However, documentation is written to be read (much more than written), therefore also reader oriented aspects are important, like index/table-of-contents, full-text search, style consistency, .. If the project pursues any end-users/reader oriented goals, then it's good to mention them on landing page also. Maybe, another 3 columns below those?

[Geobert]

Thanks for your feedback!

Unfortunately, I've been a bit carried away and multiples collections is not a thing (yet)
As for tagging and categories, they are here but we can't do much with them at the moment (displaying them only).

I'm working on indexation on tags and categories right now (tags being ready in a PR).

Discussion about this landing page is here #57