pooria - 2 months ago

Hi

First of all, I'm really exhausted by very bad and patchy docs (I know that you are busy and this takes a long time and I appreciate your efforts though).

There are a few things that confuse me:

1- You introduced Streams as database tables. So if that's it, so what is Streams "Platform" ? If you just call tables streams, so why there is a whole documentation on this with a lot of functions, services, UI, ....

2- Why you keep Pyrocms Docs and Streams Platform docs separate? Is this one project ore two projects combined? :(

3- In https://pyrocms.com/help/addon-development/modules/scaffolding-modules page, There is written:

Routes and Controller
A routes file named after your stream will be generated in the /resources/routes directory of your addon. The routes will provide default index, create, and edit. You can copy these into your addon service provider or leave them here.

But in fact only config and lang directories are created in resources directory of the module!

I wish the documentation will follow the way of Laravel's or Twig's which are comprehensive yet comprehensible! :P

radic - 2 months ago

This is really something i have been struggling with a lot as well. The documentation is all over the place and is very annoying to learn from. Primarily i think the navigation and structure is the main issue that should be addressed.

  • Put all documentation links into a global sidebar in a tree structure
  • Move the documentation files out from all the package repos and into a single dedicated documentation repository
  • Improve the documentation reading flow, so that all documentation topics are handled from A to Z instead of the current approach.
  • Enable a way for users to contribute to docs easily. Github pull request/commit would probably be good. Submitting drafts and discussing changes/ideas/opinions for each page/change. Making it very open/accessible/fast for anyone to partiicipate in improving.
  • Integrate user comments (disqus or smthing) on every doc page. I just noticed this is already done, but it should be more advertised/promoted.

finnito - 2 months ago

I have read that @ryanthompson is working on 4.0 and a new website, so I would imagine that many of these concerns might be addressed there. I do agree that the docs are difficult to navigate, and having to navigate elsewhere to view the guides can be irritating as well.

frednwt - 2 months ago

@pooria

  1. Streams is the also the name of the Platform itself.
  2. Because it is not the same thing. The platform is a development platform and it's called Streams Platform. And PyroCMS is... a CMS (yes yes I swear). PyroCMS is create using the Streams Platform. If you want to compare, it is like a car and its engine.
  3. The routes are not created in resources anymore but directly in the ModuleServiceProvider.php. I guess the docs are a bit outdated. :)

ryanthompson - 2 months ago

Hey guys! I appreciate you reaching out about this stuff cause it's really the kinda truth that needs to be heard. And while some we're more aware of than others it does indeed take some time to rectify. To be completely transparent, a TON of my time in the last few months has been focused on finishing up a very large side project. So movement in these areas (docs primarily - and testing) has been slow. We'll enjoy more docs and organization when that finishes. So bare with me! @finnlesueurgmailcom You're right, I also have been working on some core fundamentals that are involved with 4.0. Again touching on the sorest of spots (one being performance). But that's kinda been set aside as I proved my proof of concepts there for the most part.

Streams is a concept / pattern. The engine of Pyro has it's namesake, the "Streams Platform". And the DB streams tables are core operational tables used to power it all. It's indeed confusing and something I've kinda struggled with for a while how to best illustrate and convey that message. I have some ideas and they all depend on changes to docs which are well on their way.

Documentation is kept in the respective addons because it's easiest to maintain from that perspective. Same repo. However the EASIEST way to organize it all is what we have now, which kinda sucks. It's very disjointed and that's a big part of what I am working on with docs. Cleaning them up - and organizing them into a central and more flowing presentation. They'll still be separated behind the scenes but it won't be so awkward and "where the hell do I look?" once finished.

Docs kinda run the gamut from too detailed to too sparse it seems. Most of that is because of organization and style in writing. It's EXHAUSTING writing technical documents. As time went on I wrote more like Laravel - with example usage as I could though I was still following older templates. If I were to write the entire public API and every trick in the book all out.. it would be an encyclopedia britanica. Not to mention it would be hell to maintain. So to remedy this I am working on clearing up docs, organizing them, simplifying them, and teaching core principles and 90% use case stuff and covering HOW to do the latter 10% based on public API documentation built from doc blocks. People need to get in fast, figure out how to accomplish the task at hand, then learn principles to take deeper as they grow as a developer in Laravel / Pyro. It's a fine line if you ask me and again something that takes time as well.

@radic the organization will be much more a tune to what you are suggesting and there will be comments as well! Good news :-)

I've got a draft of organization and will try and finish up my templating guideline for docs and post it in Road Map cause I want them to be peer reviewed. I'll make that priority to try and get that finished and up in the next few days for review. Docs are also already editable via PRs.

@frednwt you can still use routes.php files. Just like you can still ship pre-packaged composer dependencies per addon as needed but.. it's a matter of documenting that without confusing others (advanced eyes only). We have trouble as it is so introducing more advanced techniques right now in docs is not a good idea I think. Fix the flow, fix the organization, standardize them, then continue with development of content / advanced stuff after we establish a better foundation.

Hope this all makes sense! Feel free to ask me any questions about it :-)

I sincerely appreciate you guys sticking about and helping each other out and sharing your opinions candidly and respectfully with me!

- Ryan

ryanthompson - 2 months ago

@finnlesueurgmailcom I had thoughts of putting guides into docs as they'll change their nature a bit from technical to guide oriented. Then potentially replacing guides with larger recipe type articles. Maybe user guides? Idk.

finnito - 2 months ago

@ryanthompson you would honestly know better than I would but centralizing all that stuff would be the main thing. I think the guides are great at the moment and I used them quite a lot.

That said, I’m travelling and often without wifi so I read the source code as my documentation more and more, hah, and also I used http://ricks-apps.com/osx/sitesucker/index.html to download a local copy of pyrocms.com so I can browse it at my pleasure.

Because I’m often without wifi I haven’t looked into it much, but I use https://kapeli.com/dash extensively for all my work since I’m offline so much and I would really like to work to create a PyroCMS docset.

pooria - 2 months ago

@ryanthompson I love this project and I think its architecture is intuitive. I would like to help in any way I can. At least I can make pyrocms's website look better :)

ryanthompson - 2 months ago

@pooria PM me on Slack if you could please :-)

I would love to chat more with you!