Official Phabricator's documentation license

Hello everyone! :slight_smile:

First question:

  1. Is the Phabricator’s documentation under CC BY-SA or something like?
    ◉ Introduction

Second question:

  1. How to contribute to the documentation?

About this last question, maybe people can just go in Wikibooks to write their dirty notes in order to do not flood upstream documentation with rubbish (like this dirty Harbormaster page on Wikibooks). But maybe some people can just contribute to upstream.

Thank you so much for the info!

Is the Phabricator’s documentation under CC BY-SA or something like?

It’s Apache 2, just like the rest of the project.

How to contribute to the documentation?

There’s no special method for contributing documentation changes. Historically, most proposed documentation changes aren’t things I want to maintain, just like most non-documentation patches aren’t things I want to maintain.

One common reason I don’t want to maintain a documentation change is that it is too narrow and describes something very specific which isn’t likely to help very many users. I think a 5-page setup document that describes 95% of cases is better than a 500-page setup document that describes 99% of cases.

If you believe the documentation is deficient and would like to improve it, you should start by identifying the deficiency in a report here (“I tried to set up X, I read documents Y, I succeeded/failed for reason Z, having a clearer understanding of Q might have helped”) and we can look at ways to improve the experience you had.

I’d almost always prefer to find a non-documentation way to solve problems if possible (e.g., have Phabricator detect that you missed Q and raise a warning, or guess the right value of Q automatically, or whatever else) because users don’t reliably read documentation. In a perfect world, Phabricator would have very little documentation because most systems would be self-explanatory, error-detecting, error-correcting, explained inline, etc.

1 Like

It’s Apache 2, just like the rest of the project.

That’s amazing! Maybe it can be added a small note somewhere in this page (or in a sub-page as well) for maximum information and simplify authority control:

https://secure.phabricator.com/book/phabricator/

you should start by identifying the deficiency in a report here

Yup.

For example here:

https://secure.phabricator.com/book/phabricator/article/configuring_file_storage/

It’s maybe not so obvious what ./bin/files migrate --engine XXX accepts as valid engine code. Someone have to guess that from the cited storage.XXX configurations you get these codes.

Maybe just adding a column in the “Storage Engines” table with the code would recap this concept.

What do you think about? Thank you!