1393767 - [documentation] Add documentation about adding a new DevTools preference

Status: RESOLVED FIXED

(DevTools :: General, enhancement)

Description

[Julian Descottes [:jdescottes]]

Adding a preference to DevTools cna be confusing, especially for contributors using launchpad. Each project using launchpad has its own way of defining default prefs.

We should have a documentation page that goes through:
- an overview of the prefs service we use in Firefox (Services.prefs)
- the shim from devtools-modules that mimics Services.prefs for launchpad projects
- how to add a new pref (with specific sections for each project using launchpad) 

I opened a related issue on GitHub : https://github.com/devtools-html/devtools-core/issues/612 

The goal would be to improve the error messages of our services shim to point to the documentation page created here.

Comment 1

[Julian Descottes [:jdescottes]]

Attachment: Bug 1393767 - add documentation about DevTools preferences;

Review commit: https://reviewboard.mozilla.org/r/173682/diff/#index_header
See other reviews: https://reviewboard.mozilla.org/r/173682/

Comment 2

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review179112

::: devtools/docs/SUMMARY.md:9
(Diff revision 1)
>  * [Getting started](getting-started/README.md)
>    * [Where is the code?](getting-started/where-is-the-code.md)
>    * [Architecture overview](getting-started/architecture-overview.md)
>    * [Set up to build DevTools](getting-started/build.md)
>    * [Development profiles](getting-started/development-profiles.md)
> +  * [Preferences in DevTools](getting-started/preferences.md)

I don't think this should belong in the 'getting started' section - it would be totally overwhelming for a beginner! (which is the aim of the section).

In fact, I believe it should possibly have its own section.

Are there other cases in which we store data in the profiles? If not, I'd place this new file above the 'Automated tests' section on the summary.md file.

Otherwise if we're storing more data (and I think we are, with IndexedDB?), we should have a section about "Storing data" or similar, and have this as a child section. It's fine if it's only one page for now, we can add more content afterwards (file a bug!)

::: devtools/docs/getting-started/preferences.md:1
(Diff revision 1)
> +# Preferences in DevTools

This is the DevTools documentation, so I don't think we need to reiterate 'DevTools' so much that the title is 'in DevTools', etc.

I have lots of suggestions but I think it'll be easier/shorter to file a bug and send my patch :)

Comment 3

[Julian Descottes [:jdescottes]]

Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

Review request updated; see interdiff: https://reviewboard.mozilla.org/r/173682/diff/1-2/

Comment 4

[Julian Descottes [:jdescottes]]

Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review179112

> I don't think this should belong in the 'getting started' section - it would be totally overwhelming for a beginner! (which is the aim of the section).
> 
> In fact, I believe it should possibly have its own section.
> 
> Are there other cases in which we store data in the profiles? If not, I'd place this new file above the 'Automated tests' section on the summary.md file.
> 
> Otherwise if we're storing more data (and I think we are, with IndexedDB?), we should have a section about "Storing data" or similar, and have this as a child section. It's fine if it's only one page for now, we can add more content afterwards (file a bug!)

Erf sorry I missed the review! Thanks!

> In fact, I believe it should possibly have its own section.

Yes, I was not sure about the category either. While technically it's true that we use indexeddb for devtools, I am ot sure it is the same kind of documentation. Until we have doc for this I'd prefer to keep preferences as a single page then.

> This is the DevTools documentation, so I don't think we need to reiterate 'DevTools' so much that the title is 'in DevTools', etc.
> 
> I have lots of suggestions but I think it'll be easier/shorter to file a bug and send my patch :)

Fixed. Feel free to modify in a followup!

Comment 5

[Soledad Penades [:sole] [:spenades]]

Comment on attachment 8902202 [details]
Bug 1393767 - add documentation about DevTools preferences;

https://reviewboard.mozilla.org/r/173682/#review180470

this is so much better! I will follow up!

Comment 6

[Pulsebot]

Pushed by [e-mail]:
https://hg.mozilla.org/integration/autoland/rev/dd20802d1472
add documentation about DevTools preferences;r=sole

Comment 7

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

https://hg.mozilla.org/mozilla-central/rev/dd20802d1472