How to structure Stancy documentation?

How to structure Stancy documentation?

Gummibeer

Astroneer
Moderator
Local time
00:29
Joined
Oct 5, 2019
Messages
1,150
Pronouns
he/him

Hey all,

I need some help how I should structure the Stancy documentation. It's my first fully self written (except contributions) open source package which I also have to write documentation for. I'm really not good in documentation structuring at all. šŸ˜“
Is there anyone who has some good tips how to structure one? So should I create a page for every usage step, should I explain every class or what do you think / would you prefer?
Primary because I've written every single line, wrote tests for them (100% coverage) it's pretty hard for me to switch perspective and imagine what a person that never heard about Development - Stancy would need to get started and how he would find everything. šŸ¤”

 

Adam

Mr. Webwide
Administrator
Local time
23:29
Joined
Sep 24, 2019
Messages
1,243
Pronouns
he/him

I hope you can find some inspiration here!


Perhaps since you are extending Lumen/Laravel, emulating the style of the Laravel docs would be familiar to your userbase? I think Lumen's are nicer than Laravels.

 
Last edited:

tom

Creator of StickerRunĀ®
Community Team
Local time
00:29
Joined
Oct 13, 2019
Messages
258

I love the simplicity of the documentation! It looks clean and focused on the content.

What I'm missing is the "How can I use it for my project?". Some use cases or examples on how to integrate this into a live website.
Basically a "I have a Porsche and would like to switch from fuel to an electrical engine. How can I do this?". A quick setup, 5 easy steps to get it up and running for example.

Also some kind of feature set and roadmap would be great. So I can compare the features to the other CMS for Laravel and Lumen or just to be able to see if this would fit my current use case.

 

Gummibeer

Astroneer
Moderator
Local time
00:29
Joined
Oct 5, 2019
Messages
1,150
Pronouns
he/him

Thanks, will try to improve. šŸ˜Š

simplicity
That's exactly what the package is about. And it's the reason why I don't have a comparison - because all other CMS packages I know kind of prevent you from using the normal Laravel/Lumen as is.
But I will add a Quickstart guide which shows the basic setup and links to all the other pages.

At the end the use is what's described plus this in your routes:

PHP:
use Astrotomic\Stancy\Facades\PageFactory;
use Illuminate\Support\Facades\Route;

Route::get('/', function () {
    return PageFactory::makeFromSheetName('static', 'home');
});

This will render the configured home page from the static sheet collection.

 

tom

Creator of StickerRunĀ®
Community Team
Local time
00:29
Joined
Oct 13, 2019
Messages
258

Gotcha, that's perfect! Yeah those small examples are great and do more good than 10 pages of extensive documentation, imho.
I like reading the "Getting started" pages of documentation as I mostly don't have time to go through every page of the docs.

 

Gummibeer

Astroneer
Moderator
Local time
00:29
Joined
Oct 5, 2019
Messages
1,150
Pronouns
he/him

@tom Is this what you wanted to see?


I walk through every step in detail to ad a static page, a blog (or similar) and how to enable sitemap and feeds. It also links every detail doc page in the related context.
I've decided to do a lot of code and very few explanation text around it. Beware - some of the code sections contain multiple files (file tabs on top of the code block.

 

tom

Creator of StickerRunĀ®
Community Team
Local time
00:29
Joined
Oct 13, 2019
Messages
258

This! Yes, thatā€˜s exactly what I meant. Wow, every documentation should have something like this. Makes diving into it much easier in my opinion.

 

Gummibeer

Astroneer
Moderator
Local time
00:29
Joined
Oct 5, 2019
Messages
1,150
Pronouns
he/him

Yeah, documentation at all is a pretty hard topic. Writing it as the dev you has written the code isn't this easy. The problem is that you know every piece of code, every hidden hook and so on.
Moving back and imagine what someone who has never seen this code will need to get started with it isn't easy.

I hope that I haven't forgot any step - I've reconstructed most parts from the Laravel demo app. If something could get improved, is missing or not clear enough - just write here, an issue or even open a PR to fix it. šŸ˜Š

 
Top