search

sandstorm-io / sandstorm

Sandstorm is a self-hostable web productivity suite. It's implemented as a security-hardened web app package manager.
https://sandstorm.io
Other
6.72k stars 705 forks source link

Developer docs should be sorted into more categories #3212

Closed ocdtrekkie closed 4 years ago

ocdtrekkie commented 4 years ago

Docs has a limitation of two levels of docs based on the theme. This may justify a theme switch someday. But for now I think we can use "Developing with..."

Right now there is stuff about vagrant-spk dev and spk dev and Powerbox APIs all in one big poorly-sorted category. I would rather break down into:

  1. Developing with vagrant-spk
    • vagrant-spk tutorial
    • platform stacks
  2. Developing with spk
    • spk tutorial
    • raw packaging
  3. Developing with meteor-spk (though this might be too specific for top-level placement)
  4. Developing with docker-spk (docs don't exist yet, maybe should?)
    • docker-spk tutorial
  5. Integrating apps with Sandstorm
    • powerbox
    • email from apps
ocdtrekkie commented 4 years ago

I am not sure where #3213 would fit into either this or the existing docs. Platform-specific packaging info is a bit disparate between "raw Sandstorm hacking" info and vagrant-spk stack info. Perhaps we need another section about how to package apps written in specific languages/frameworks, including what strategies are available.

ocdtrekkie commented 4 years ago

Perhaps as meteor-spk and docker-spk are less-used and less-documented, we should have an "Other tools" heading which has single-page documents on each.

zenhack commented 4 years ago

i think I'd put 1-4 under a broader category of "Buidling and packaging apps."

I agree with having an "Other tools" section.

ocdtrekkie commented 4 years ago

So, the problem is, there's about a half-dozen vagrant-spk-specific pages, and we can't do multiple layers with our current Docs theme. So we either have to dump all of our different dev tools' pages into one big category like we have now (I hate this), have a category for each dev tool (proposed above), or find an alternative theme that will let us have more levels of documentation (possibly worth investing time in).

zenhack commented 4 years ago

Ah, that's annoying. I guess my take then would be to use your proposal above for the short term, and maybe look into another theme in the long term.

Quoting Jacob Weisz (2020-02-26 12:39:40)

So, the problem is, there's about a half-dozen vagrant-spk-specific pages, and we can't do multiple layers with our current Docs theme. So we either have to dump all of our different dev tools' pages into one big category like we have now (I hate this), have a category for each dev tool (proposed above), or find an alternative theme that will let us have more levels of documentation (possibly worth investing time in).

-- You are receiving this because you commented. Reply to this email directly, [1]view it on GitHub, or [2]unsubscribe.

Verweise

  1. https://github.com/sandstorm-io/sandstorm/issues/3212?email_source=notifications&email_token=AAGXYPSASXRZW2MP4CFJHLTRE2SNZA5CNFSM4KTFXGUKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOENBFUWI#issuecomment-591551065
  2. https://github.com/notifications/unsubscribe-auth/AAGXYPWGFJSGKIJHGSB2JMLRE2SNZANCNFSM4KTFXGUA
zdb999 commented 4 years ago

MkDocs has updated their version of ReadTheDocs, and the new version allows for much deeper nesting. I pulled in the latest copy, and have verified locally that the custom css modifications still work correctly, and opened a pull request (https://github.com/sandstorm-io/sandstorm/pull/3245) to allow for greater nesting.

zdb999 commented 4 years ago

I would like to work on Doc reorganization over the next few weeks. While most things are documented somewhere, I think the flow from the user's perspective could be greatly improved. I've been trying to package my first app, and I would like to fix some of the issues I found. I also think this would be a good way for me to start contributing to the project.

ocdtrekkie commented 4 years ago

So once #3246 is tested and merged, we can do a bit more of a tier structure!

This is where I would start. Some of the vagrant-spk pages should get broken away and rewritten. Code and service dependencies pages should probably be moved into platform-specific tips, but I want to start by getting the structure in place.