Guidelines for documenting SB-Plus

[hippalectryon-0]

I've just started the process of updating the documentation to reflect the SB-Plus UI.

In doing so, I'm deleting parts that were relevant for the Legacy Sandboxie but that don't fit SB-Plus. As there are no guidelines for updating the documentation, I'm not sure if this is the right way, or if we should keep two separate documentations ?

Moreover, if I have questions regarding some features to document, where should I ask ? Should I open an issue here, open an issue on the Sandboxie repo, use a forum, ... ?

[isaak654]

@mitchcapper is doing the same thing, so you may want to keep in touch with each other.

[hippalectryon-0]

@mitchcapper if you want to collaborate so that we don't do twice the same thing (and so that our edits are consistent), don't hesitate to push your changes to https://github.com/mitchcapper/sandboxie-docs ;)
You can view mine over at https://github.com/hippalectryon-0/sandboxie-docs

[isaak654]

The starting point would be to not overwrite Sandboxie Classic pages with Plus, we still have Classic users in other websites like Wilders and Sandboxie Plus still contains SbieCtrl.exe in the main folder for legacy users because of a past complaint.

[hippalectryon-0]

That's a good point. I'm going to duplicate every updated resource for now, prefixed by SP_ (ex SP_README.md)

[mitchcapper]

HI @hippalectryon-0 happy you filed a ticket here. There will be three PR I will have in the next few days:

• the first is just updated trace documentation, but will have the first hints towards a new method for talking about the two versions. While not specifically related to this I couldn't really update that documentation without talking about the two versions and it quickly became chicken and the egg problem for which to do first.
• The second will add a few SBPLus pages to have the basics documented (somewhat required for the 3rd PR).
• The final 3rd one will be much larger in pages it touches and is a PR where the bulk renaming occurs.

The 3 will probably want to be merged all at once to avoid broken docs, but are separated out to provide some single task per commit standardization.

The goal there is to A) Make sure any time the classic version is referenced it is done so as such. So not just in SB Control but in Classic SB Control. That way a user instantly knows if the documentation is on classic or the plus version. B) Updated consistency in referring to the Agent program when not talking about a specific version. If something applies to plus and classic rather than just being "in SB Control you can terminate all running apps in a sandbox" it will be "In the SB agent you can terminate all running apps in a sandbox". C) Make sure all references to SB Plus agent use that terminology as well.

Now in an effort to minimize chaos and keep existing links working no pages will actually be renamed. While it may say in the "Classic SB General Tips" for the page title the file is still GeneralTips.md.

There is the desire to preserve all the good documentation that is already there (virtually all about the classic). I do n't think the goal it to have two separate manuals however. The approach I have been taking for that is:

1. If the page references are generic and don't specifically apply to Classic / Plus to just refer to the agent as the SB Agent (per above).
2. If there are somewhat critical different instructions for each agent but still a minor part of the page to add SB Plus documentation ahead of the classic and then have the existing classic follow it (IE: "To disable software compatibility checks go to Global Options in SB Plus and under the Compatibility tab check "In the future don't check software compatibility. For SB Classic Control go to Global Settings and make sure the box Check Software compatibility at startup is unchecked.".
3. If there are major differences without a lot of common overlap, two versions of the page. For the trace documentation for example there is a common page on SB Tracing and reading the logs and then a specific page on the UI options and enabling for SB Plus and another Classic SB Control.
4. If there is something not documented in SB Classic there is less emphasis in writing new classic documentation. Classic is primarily used by users who have used the product for considerable time and know the UI well.

The goal is to avoid two separate sets of documentation completely (as that would likely lead to a lot of duplication and making updating common core items more laborious). It also makes it clearer what is new documentation vs just bulk duplication of old docs.

I think the best way for us to collaborate would be:

• I will make my first PR today for the new trace docs will show somewhat the updated writing style I am mentioning
• I will commit up what I have so far to new new branches in my report for PR 2 and 3 rather than doing one monolithic commit for each. I squash my PR in the official PRs anyway so having multiple commits isn't an issue.
• PR 3 above touches the largest number of pages and is likely a single person job. It should only take a day or two but should make sure the terminology is fairly standardized.
• I only briefly looked at all the new doc branch you have but it looks like you have primarily been writing actual content on SB Plus so that should work out well. Aside from the new trace docs, and the intro page on SB Plus with its screenshots and a page on the SB Agents I shifted most of my focus to standardizing things first

While generally forking off a future PR is not the best option if you want to do so while I am working currently on finishing the general renaming it may make the merging slightly easier. Otherwise I think after the fact won't cause much issue either. In addition, if you have any feedback or suggestions on some of what is proposed or as you see the WIP fantastic. I am not a documentation guru just (like you) saw a bit of a gap on the new SB Plus docs so wanted to get some of the things I was understanding documented.

My email is on my GH page as well in terms of having more real-time conversation if easier.

[hippalectryon-0]

Hi @mitchcapper, thanks for the detailed answer.

In that case, since time is not of the essence, here's a suggestion for how we could work this out:

Let's give priority to your PR and ideas, keep working as usual on your PRs over the following few days. In the meantime, I'll continue updating the pages and screenshots to the SBPlus UI in my branch, even if there's quite a bit of duplication. This will allow me to get a better overview of what's in the docs, the issues it might have, and collect relevant screenshots. Then, when your PRs are somewhat "finished", I'll see how I can incorporate my changes into your new architecture.

In short: don't mind me for now, but ping me once your global PR(s) is(are) ready, and I'll see how I can contribute meaningfully :)

[hippalectryon-0]

@mitchcapper

Now in an effort to minimize chaos and keep existing links working no pages will actually be renamed. While it may say in the "Classic SB General Tips" for the page title the file is still GeneralTips.md.

I do have one point of disagreement though: I do not think that leaving the file names as-is is a great idea, many of them are quite badly chosen, and with proper tools (like the reformatting option of most IDE) the risk of breaking links while renaming is minimal

[mitchcapper]

Oh I 100% agree on that front, I think the current file arrangement happened over time as more and more documentation came into place, but is greatly in need of a reorganization. Sadly, I meant breaking external links to documentation which that would do. I agree we should be able to internally rename everything and not break internal links. I am totally up front a better documentation file naming convention, but that is above my pay grade for if/when that happens:)

[mitchcapper]

First two PR are up going to have them reviewed before doing the 3rd. To see what the 3rd would look like:
https://github.com/mitchcapper/sandboxie-docs/blob/classic_plus_clarify_rewrite/Content/SandboxieIni.md
is a decent example.

Note I did a few content pages for SBPlus but as you have mostly done actual contact for SBPlus I stopped doing any further.

[hippalectryon-0]

@mitchcapper
1. I notice that wherever there's a different setting for Legacy and Plus, you used parenthesis, like so:

"This can be done in the Sandboxie Plus app menu under "Options -> Trace Logging" (or in Sandboxie Classic the File Menu -> Resource Access Monitor)."

"You are advised to use the Sandboxie Plus Agent Sandboxie Plus to make configuration changes (or for Classic, Sandboxie Control)."

This pattern is bound to happen a great number of time, and I fear it might clutter the documentation for users looking only for a specific version, since the details for both Legacy and Plus are on the same line.

What do you think about using the icons for a more concise formatting, like so :

• for very short differences, we keep the same line
  This can be done in "Options -> Trace Logging" ( File Menu -> Resource Access Monitor)
• for medium differences, we do a paragraph/bullet each
  • lorem ipsum, Menu -> Something > Click, etc etc
  • lorem ipsum 2, Other Menu > A tab > Do thing
• for long differences, we do a page for each (?)

2. See https://github.com/mitchcapper/sandboxie-docs/blob/643f68d74303ce1d311314629adad7f86e06f213/Content/SBPlusSandboxMenu.md for example: doing it this way introduces a lot of redundancy (for ex. the Stop All Processes is the same across Legacy and Plus, and used in many places in Plus.)

The way I handled that in my branch is by documenting what it does at one place, and at every other place write See Original documentation page .

How do you think we should handle that ?

[isaak654]

1. A new suggestion was indicated in this comment:

I also wanted to know which difference are between Application Compartment and normal sandbox.
Maybe it's useful to have these differences in the documentation?

2. Issues/discussions with documentation label may be considered for future documentation updates:
   https://github.com/sandboxie-plus/Sandboxie/issues?q=label%3Adocumentation
   https://github.com/sandboxie-plus/Sandboxie/discussions?discussions_q=label%3Adocumentation

[mitchcapper]

Documentation tagging

Choice: None needed

@isaak654 thank you for creating the documentation tags. Aside from tagging main repo issues/discussions until they can be properly documented it would be good to do so for any major feature changes. The changelogs might be enough to review (trying to filter out pre-release duplicate notes). Other options would be filing a new issue in this repo for major changes to document or starting a discussion when there are major changes in the main repo and tagging it with the documentation tag.

File Renaming

Choice: Already decided to avoid renaming.

The initial documentation has come together overtime and clearly did not plan for a second agent. There are no folders or grouping/naming conventions. It is very difficult to use the raw files to find the information desired, but with the good indexing and page linkage the output works well in the final product. Renaming would allow to tag classic specific pages with Classic in the file name. Updating page names would break existing links and documentation. The benefits or re-organization did not outweigh the costs at this point. As new SBPlus pages are written we can try to have more logical grouping of these pages. For some new pages that have classic equivalents likely just prefixing the classic name is better than completely renaming the new page.

Classic Page Title/Links/Embeds Updates

Choice: Already decided to tag agent specific page titles with the agent, but not specifically target updating all Links.

By tagging the page titles with the agent name it makes it clear when documentation is specific to only one. For example the page titled "Tray Icon Menu" would change to "Classic Tray Icon Menu". Links can be updated as relevant but will not be searched and all tagged with the agent name during this update.

How to Refer to the UI Agent

Choice: There are two different UI's for Sandboxie Plus. We need to establish consistent naming so that users know which we are talking about, otherwise it will be easy to be confused between the two in documentation. We also need a single term to describe both clients when just referring to the UI client in general..

Strong repetitive naming should be very helpful from a user POV. Without it users may not know what agent we are talking about or what application we are referring to (if we use several different names for the same thing).

We should try to make sure the naming is not too long so that it doesn't make descriptions exceptionally long.

Potential Original Client Names

• SB Classic
• Classic Control
• SB Control
• Sandboxie Control
• Sandboxie Classic
• Classic UI
• Classic Agent

Potential SB Plus Client Names

• SB Plus
• Sandboxie Plus
• SB Plus Agent
• SB Plus UI

Potential Singular Names:

• UI Agent
• SB UI
• Sandboxie UI
• Control UI

Anything else works but we should standardize something. The benefit of Classic in the original agent name makes it very clear on which pages are about SB Control.

Default Decision

The old agent was already referred to as the Sandboxie Control app in places so "Sandboxie Control" name seems fitting. In long form could be Sandboxie Control Agent (or SB Control for short form). For the new app I believe "Sandboxie Plus" has been recommended (even though it does refer to the entire app now as well). For the singular term when needed "UI Agent" seems fitting and clear.

Conversion of Classic Specific Pages

Choice: For pages that are heavy UI pages that are having SBPlus versions made what should we do for links not yet converted.

For pages like: sandboxie-docs/SBPlusSandboxMenu.md at 643f68d74303ce1d311314629adad7f86e06f213 · sandboxie-plus/sandboxie-docs · GitHub it starts from a Classic page with updated images, and instructions for the proper SB Plus pages. Pages like that may have many links to other pages needing new versions, but we are unlikely to write them all at the same time. I initially proposed 5 options:

• Link to fake pages that don't exist yet, probably a bad idea as breaks things for others

• Link to actual placeholder pages that just say coming soon.

• Remove the links but leave the text, allowing them to be hyperlinked later

• Remove all the text that talks about something we haven't documented (more annoying to catch all the ones we need to re-link later and may read inconsistently).

• Leave the links we haven't re-written content on point to Classic documentation

Default Decision

I recommend the last option most, as sometimes while the menus/UI may not be the same using the classic documentation is better than nothing for a user. It is also the easiest as pages not yet fully converted don't need any changes. The biggest downside is it is much harder to know what still needs to be converted. The other likely best choice is the placeholder pages. These would not take a good bit of time to make, and if we wanted to do the best service we could even have a message about the classic documentation and a link to it.

Re: @hippalectryon-0's suggestions:

• Agreed it can add clutter with my current style.

The icons

Choice: Rather than using words for the UI agent we use icons?

Positives

• Reduced text
• visually able to easily identify commands to run on a page

Potential Negatives

• Reduced support for copy and paste but you can name icons in MD that seems to work decently. This would work fine for copying for reference but copying text with the icons is not well preserved when going to paste into another markdown editor (even just creating a new GH issue for example). I didn't try many editors but none seemed to paste properly. Copying the markdown source itself would work, but still a bit of a challenge for ease of editing.

• It may be less good from an accessibility POV. I don't have Jaw's or similar currently installed to see how much more disruptive the lines are for readers with the icons.

Default Decision

• I am good with either, it save some words and we can write a doc page about using it for new docs. I think it isn't very standard across other docs I have seen, but the concept is straightforward for users. If no input otherwise, I would default to accepting the proposal.

The broader division of talking about the agents

Choice: How do we try to intermix documentation of Classic and Plus or segment the pages?

@hippalectryon-0 I think their initial plan was to essentially rename and archive the original classic pages and rewrite all documentation in the form of new docs with a link to "Original Documentation". They proposed a second option based on my initial sample of:

• for very short differences, we keep the same line
  This can be done in "Options -> Trace Logging" ( File Menu -> Resource Access Monitor)

• for medium differences, we do a paragraph/bullet each

  • lorem ipsum, Menu -> Something > Click, etc etc
  • lorem ipsum 2, Other Menu > A tab > Do thing

• for long differences, we do a page for each (?)

This is fairly well put. I would use a separate page for large amounts of text where the pages woudld be mostly different. I would clarify this as: it wouldn't be about the difference in a single instance on the page but rather the amount of content on a page that is agent specific vs the amount of content that applies to everything. For example on https://github.com/mitchcapper/sandboxie-docs/blob/classic_plus_clarify_rewrite/Content/SandboxieIni.md there are only three mentions of Sandboxie Control on the page, with most of the content being for both.

Separate Solution

• Archiving old pages and only documenting SB Plus Agent is the cleanest for new users and likely the easiest solution.
• Downside is it makes SB Classic users have a harder time and a bigger pain for updating documentation that is not agent specific (as it is in two places).

Mixed Solution

• Common information is in one location with a single copy, minor differences between the agents is noted on page. For larger differences if there is a large amount of common content and agent specific content trying to split into a common page and the two agent pages would likely be best. While most SB Classic documentation will not be focused on in the future, this would still allow major non-agent specific items to be available for classic users to understand.

• It is not as clean and a bit more tedious during the initial separation and cleanup of pages. If there is convergence on SB PLus expected then it may not be worth trying to maintain it in this fashion. It would be fairly easy to remove Classic documentation at a later date if desired.

Default Decision

• I still think there are a large number of classic users and there is benefit of making this change less disruptive and keep as much shared documentation as possible. I would go for the mixed solution and only change course if that looks like it ends up looking far less doable.

[isaak654]

@isaak654 thank you for creating the documentation tags. Aside from tagging main repo issues/discussions until they can be properly documented it would be good to do so for any major feature changes. The changelogs might be enough to review (trying to filter out pre-release duplicate notes). Other options would be filing a new issue in this repo for major changes to document or starting a discussion when there are major changes in the main repo and tagging it with the documentation tag.

Most implemented features are currently marked with the "added in next build" label, so I've just added the "documentation" label to the most relevant ones I remember, while the future feature requests are currently marked with the "future development" label until completion.

For any suggestion about other issues I may have missed, please let me know which ones you would like to label or not.

---

About the "How to Refer to the UI Agent" part, I suggest these as personal preference:

Potential Original Client Names: Classic UI
Potential SB Plus Client Names: SB Plus UI
Potential Singular Names: Sandboxie UI

About the "Conversion of Classic Specific Pages" part, you may want to take in consideration the following page which has 6 missing placeholder pages: https://github.com/sandboxie-plus/sandboxie-docs/blob/main/docs/Content/ResourceAccess.md

About the rest, I agree with your default decisions.

[mitchcapper]

About the "Conversion of Classic Specific Pages" part, you may want to take in consideration the following page which has 6 missing placeholder pages: https://github.com/sandboxie-plus/sandboxie-docs/blob/main/docs/Content/ResourceAccess.md

Yeah the missing pages there are obvious and make sense. The issue I have with not linking on page conversion is two fold:

• For links in paragraphs (ie https://sandboxie-plus.github.io/sandboxie-docs/Content/FilesAndFoldersView.html ) it can be harder to see that items need linking, vs the sample above where it is clear 6 things are not yet documented.
• Linking to the Classic UI documentation in some situations may be better than linking to nothing. Either direct linking from the SB Plus UI page to the Classic UI page or (probably better) this method for example:

  Assume we have rewritten the FileAndFoldersView doc in a new SB Plus UI version of that page. We did not rewrite any of the sublinks. So the "Quick Recovery" link could link direct to the old Classic UI Quick Recovery page which would not match the SB Plus UI but may have valid information for the user. The second option would be to link it to "SBPlusQuickRecovery.md" which says "This page has not yet been documented in SB Plus UI but the Classic UI documentation page here might be helpful" (with it linking).

[SiNONiMiTY]

Hi all,

Do you think we can rewrite the sandboxie documentation using the ReadTheDocs format?

Take a look at the documentation of Unbound, a recursive dns server that has a lot of options:
https://unbound.docs.nlnetlabs.nl/en/latest/

I think this documentation format is very readable. Given that sandboxie has a lot of options, we can document it in this format.