Provide Comprehensive Documentation
Most of Plastic SCM's documentation exists in the form of blog posts and tutorials. It's scattered and incomplete.
Every command-line option, and every location and schema for every configuration file, should be documented online. Check out Docker's website - that's a great example to aspire to.
We need more specific feedback to act.
We are trying to reduce the number of config files, and in fact, everything should be configurable from GUIs, which is what most users want (we also got requests saying, no, I don’t want to learn a config file). GUIs or WebAdmin.
So, maybe the setting you’re looking for (we don’t know which one it is) is not meant to be directly set on a config file, not sure.
Anyway, our official docs are available here:
Not a bunch of blogposts :-)
`cm help fastexport` returns "Exports a repository in fast-export format." with no further instructions. There are currently zero valid Google search results for "cm fastexport". Running `cm fastexport` without any further arguments results in an error. How do we use this CLI feature?
Information about how to use Git Sync with different ports is hidden in [release notes from 6+ years ago](https://www.plasticscm.com/download/releasenotes/18.104.22.1689) instead of [the proper documentation of that feature](https://www.plasticscm.com/documentation/gitsync/plastic-scm-version-control-gitsync-guide).
I had to waste support's time to learn about "cm changeset editcomment" in the CLI and "ignore.xlinkRepository" in gitsync.conf because these features are not documented in any formal way online. Only after having learned about them, I was able to find that "ignore.xlinkRepository" is mentioned in a forum post, and "editcomment" is mentioned in a release notes.
This documentation page mentions "In the gitsync.conf file..." without indicating where gitsync.conf is to be found. Please let us know where to find gitsync.conf in the same documentation that introduces and describes it.
> our official docs are available here... Not a bunch of blogposts :-)
Unnecessary dismissive smiley-face aside, there are several technical aspects of Plastic that are explained in blog posts and release notes, but not in any other documentation:
- what's in client/diffscripts and how to use them
- the new clone command
- information about --nodata
- how to use preview tools
That's just scratching the surface. It turns out there is more in the documentation than I had thought - the blog posts are much easier to find. I've learned in checking for these that searching Google for "site:www.plasticscm.com ..." is the most effective way for me to find the real documentation, while regular queries on Google and your own site turn up mostly release notes, forum, and blog.
Many things are simply not documented anywhere. I can come up with a more specific list when I have the time. There is also some documentation on your Zendesk. As you mention, some is only available through respective GUIs and apps. Therefore, it's scattered.
Generic and guided explanations are not mutually exclusive. Unity has both. Docker has both. More importantly for you, Perforce has both. Plastic has both, too, but not comprehensively. The need for documentation that objectively, technically, and comprehensively describes the software's behavior is necessary for developers to work efficiently with your software when doing anything other than the prescribed/guided use cases.
> "cm help command gives you exactly what you need... we could also copy the same text and write it on a website. But our difference comparing to Git is that we do develop GUIs, not just commands, and most of our users use GUIs and not the command line (except for automation)"
Exactly, "except for automation". Automation is increasingly essential. Your own book and blog is increasingly encouraging CI. You're working on things like MergeBot so you clearly value automation. Why make things harder for the sysadmins? They are not a majority of your users, but they *support* a majority of your users. They are the gatekeepers that are telling my clients to stick with Perforce and not use Plastic. And it is through good automation practices that it should be minimal effort to produce both searchable and CLI-embedded documentation. It's not like you would copy-paste the text into an HTML document and have to maintain two copies.
I could live without config file documentation as long as the config files are fully manipulatable to the full extent of their schema by both GUI and CLI. This is not currently the case. In fact, much of your documentation and guidance still calls for direct modification of config files. Until that is fixed, the lack of config file documentation is and will continue to be a source of friction for your users.
Starting out with Plastic was very easy due to your focus on GUI and usability. Now that I've learned all the basics and more over several years, I'm a more advanced user that wants to do more advanced things, only to discover that Plastic dismissively disregards the essential needs of such users.
The documentation *has* improved and expanded since I began using Plastic. Which makes it strange that requests for more documentation are met with such defiance. I'm simply asking that you finish what you started, to the same degree of standards that are held by all of the other software I've mentioned on this thread.
The issue with your asking "what exactly do you need?" is that this approach will only resolve information friction one challenge at a time, with day turnaround each time, and most of those resolutions will probably never make their way into the documentation. Having a technical writer whose one and only responsibility is to own and continuously improve the quality and coverage of your documentation ecosystem would allow the rest of you can spend far less time re-explaining how your software works in private channels.
"A dedicated page per tool (consistent organization of information). Each page has a full enumeration of commands and their properties. The way that the program interprets the properties and commands is sufficiently described in a way that is generic and not for one particular use case."
It is also worth noting that this is exactly the opposite style we decided to use:
* We don't like generic explanations. They are hard to understand. We prefer a scenario guided approach, like the one we use in the Security Guide. This is because the human brain works best extracting general cases from specific ones than the opposite. At least, that's what guided all our writings in the last 10 years. The GUI guide is an example of the opposite approach, and we don't like it anymore.
* Commands: well, cm help command gives you exactly what you need. Yes, we could also copy the same text and write it on a website. But our difference comparing to Git is that we do develop GUIs, not just commands, and most of our users use GUIs and not the command line (except for automation). So, while we try to do our best to improve the CLI (we did a huge redesign like 1 year ago), it is definitely not the main UI compared to GUIs.
What do you exactly need?
Everything accessible from the docu page.
Not sure exactly what you mean by "blogposts". Yes, we have tons of blogposts, but lots of docu too :)
I have seen the book, and read quite a bit of it. It's great series of tutorials and op-eds. It's not documentation. For one, there is no mention of "clconfigureserver" anywhere in the book. There is not even a single mention of "cm find".
A dedicated page per tool (consistent organization of information). Each page has a full enumeration of commands and their properties. The way that the program interprets the properties and commands is sufficiently described in a way that is generic and not for one particular use case.
Microsoft dotnet is another good example: https://docs.microsoft.com/en-us/dotnet/core/run-time-config/compilation
Unity is another good example: https://docs.unity3d.com/Manual/CommandLineArguments.html
Git is another good example: https://git-scm.com/docs/git-config
I'm not sure if you know about PlasticSCM's book. I'll leave here the link:
Check it out and tell me if it is something you think you would use.