Welcome to our inclusive community of web designers, developers and makers.
Creating an account takes less than 30 seconds, start participating right away!
Create account

Solved How to structure Stancy documentation?

Gummibeer

Well-known member
Joined
Oct 5, 2019
Messages
546
Reaction score
424
Points
605
Age
26
Location
Hamburg, Germany
Local Time
Today, 20:39
Website
gummibeer.de
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
Joined
Sep 24, 2019
Messages
497
Reaction score
473
Points
485
Location
United Kingdom
Local Time
Today, 19:39
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:
  • Like
Reactions: Gummibeer

tom

Creator of StickerRun®
Gold Member
Community Team
Joined
Oct 13, 2019
Messages
162
Reaction score
148
Points
235
Location
Bregenz - Austria
Local Time
Today, 20:39
Website
www.stickerrun.com
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.
 
  • Like
Reactions: Gummibeer

Gummibeer

Well-known member
Joined
Oct 5, 2019
Messages
546
Reaction score
424
Points
605
Age
26
Location
Hamburg, Germany
Local Time
Today, 20:39
Website
gummibeer.de
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.
 
  • Like
Reactions: tom

tom

Creator of StickerRun®
Gold Member
Community Team
Joined
Oct 13, 2019
Messages
162
Reaction score
148
Points
235
Location
Bregenz - Austria
Local Time
Today, 20:39
Website
www.stickerrun.com
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.
 
  • Like
Reactions: Gummibeer

Gummibeer

Well-known member
Joined
Oct 5, 2019
Messages
546
Reaction score
424
Points
605
Age
26
Location
Hamburg, Germany
Local Time
Today, 20:39
Website
gummibeer.de
@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.
 
  • Like
  • Love
Reactions: Adam and tom

Gummibeer

Well-known member
Joined
Oct 5, 2019
Messages
546
Reaction score
424
Points
605
Age
26
Location
Hamburg, Germany
Local Time
Today, 20:39
Website
gummibeer.de
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. 😊
 
  • Like
Reactions: tom