How to structure Stancy documentation?

[Gummibeer]

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. 🤔

https://twitter.com/i/web/status/1182715441145360384

 

[adam]

I hope you can find some inspiration here!

PharkMillups/beautiful-docs

Pointers to useful, well-written, and otherwise beautiful documentation. - PharkMillups/beautiful-docs

github.com

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.

Installation - Lumen - PHP Micro-Framework By Laravel

Lumen - The Stunningly Fast PHP Micro-Framework By Laravel

lumen.laravel.com

 

[Gummibeer]

I've done the first pages and the structure. Any thoughts/recommendations?

Introduction

docs.astrotomic.info

 

[tom]

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]

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:

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]

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]

@tom Is this what you wanted to see?

Getting started

docs.astrotomic.info

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]

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]

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. 😊

 

[tom]

I just saw this article here: What nobody tells you about documentation

Maybe you can use 1 or 2 things from this. 😊