Closed Bug 727272 Opened 14 years ago Closed 14 years ago

The documentation is hard to navigate

Categories

(Add-on SDK Graveyard :: Documentation, defect, P1)

Product:
Add-on SDK Graveyard
Component:
Documentation
Type:
defect

Tracking

(Not tracked)

Status:
RESOLVED FIXED

People

(Reporter: jbalogh, Assigned: wbamberg)

References

Details

Attachments

(1 file)

Link to pull request 347
136 bytes, text/html
dcm
: review+
Details
Here is the SDK docs homepage: https://addons.mozilla.org/en-US/developers/docs/sdk/latest/ Here is the Django docs homepage: https://docs.djangoproject.com/en/1.3/ I can find almost anything I want to read about from the Django homepage. But it's not just about content! The Django page uses bold words and a contrasting link color so it's very scannable. The Django page separates inline section names with pipes. The SDK sidebars are an unscannable mash of words and hyphens, and parts of them disappear depending on the section I land in. When I'm using the SDK documentation I find myself opening a ton of tabs and never actually finding what I want. How do I run unit tests? 1. Google "addon sdk unit tests" 2. Follow the #2 result to https://addons.mozilla.org/en-US/developers/docs/sdk/1.1/packages/api-utils/docs/unit-test.html. 3. Change that to https://addons.mozilla.org/en-US/developers/docs/sdk/latest/packages/api-utils/docs/unit-test.html to make sure I get the latest docs. 4. Read about the API with zero examples and no indication of where to put the tests or how to run them. 5. Click on Internals Guide > Reference: https://addons.mozilla.org/en-US/developers/docs/sdk/1.4/dev-guide/module-development/reference.html (no info) 6. Nothing there, try https://addons.mozilla.org/en-US/developers/docs/sdk/1.4/packages/api-utils/api-utils.html (no info) 7. Oh, in the sidebar there's now a section that says "test-harness". Go there: https://addons.mozilla.org/en-US/developers/docs/sdk/1.4/packages/test-harness/test-harness.html 8. On the page: "For more information on testing in the Add-on SDK, see the <a>Reusable Modules</a> tutorial." 9. Go to https://addons.mozilla.org/en-US/developers/docs/sdk/1.4/dev-guide/addon-development/implementing-reusable-module.html. 10. Scan, scan, oh here is a section called "Testing Your Module". I'd link to that section but sections aren't linkable.
I've been working on trying to improve this. I'd like to know how much you think it helps: http://members.shaw.ca/vill/docs/sdk/wip/.
(In reply to Will Bamberg [:wbamberg] from comment #1) > I've been working on trying to improve this. I'd like to know how much you > think it helps: http://members.shaw.ca/vill/docs/sdk/wip/. That's looking a lot better! I would drop the border + background color on the h2s. It gets distracting. The 3-column layout makes the Getting Started section hard to read. I like the separation of high- and low-level APIs.
(In reply to Jeff Balogh (:jbalogh) from comment #2) > (In reply to Will Bamberg [:wbamberg] from comment #1) > > I've been working on trying to improve this. I'd like to know how much you > > think it helps: http://members.shaw.ca/vill/docs/sdk/wip/. > > That's looking a lot better! Thanks for taking the time to look! > > I would drop the border + background color on the h2s. It gets distracting. > I'll try it out. > The 3-column layout makes the Getting Started section hard to read. > Do you think 2-column would work better, or just one? (I started out with 2. Chose multiple columns to make it more compact, but if it's not helpful I can revert it.) > I like the separation of high- and low-level APIs.
(In reply to Will Bamberg [:wbamberg] from comment #3) > > The 3-column layout makes the Getting Started section hard to read. > > > > Do you think 2-column would work better, or just one? (I started out with 2. > Chose multiple columns to make it more compact, but if it's not helpful I > can revert it.) I like the columns in the High Level API section since there's enough content to spread across the columns. I think smaller sections are easier to read with a single column, so they remain scannable.
Assignee: nobody → wbamberg
I've made a pull request containing these changes
...at https://github.com/mozilla/addon-sdk/pull/347. I'll raise three other bugs to cover review for the new tutorial content. I'll make this bug depend on those other three bugs: so this is the main bug covering all the changes. In this bug I'd like some review of: 1) the style and structural changes I've made: this doesn't need to be someone familiar with the SDK. 2) the corresponding changes in the doc infrastructure, which I'll call out explicitly, but which includes things like changes to the Python scripts and CSS 3) any content not covered in the "tutorial content" bugs: again, I'll call this out explicitly, but it include things like the new tutorial page: https://github.com/mozilla/addon-sdk/pull/347/files#diff-32. There's not much of this stuff.
Depends on: 728056
Depends on: 728061
Depends on: 728057
Dave: could you review this huge pull request from the point of view of overall structure and style? It also involves taking a look at files not covered by the tutorial content bugs. There are a lot of these, but most of the changes are very small. In an attempt to make it less painful I've listed each relevant file below, linked it in the PR, and summarised the changes: doc/dev-guide-source/addon-development/guides.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-7 - rewritten for the new style/structure doc/dev-guide-source/addon-development/high-level-apis.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-8 - new page for the new structure, to reflect third-party/high/low level API division doc/dev-guide-source/addon-development/low-level-apis.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-12 - new page for the new structure, to reflect third-party/high/low level API division: basically a port of the old: https://addons.mozilla.org/en-US/developers/docs/sdk/latest/dev-guide/module-development/about.html doc/dev-guide-source/addon-development/mobile.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-13 - add missing license header, and link to getting started doc/dev-guide-source/addon-development/sdk-vs-xul.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-15 - update links doc/dev-guide-source/addon-development/third-party-apis.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-16 - new page for the new structure, to reflect third-party/high/low level API division doc/dev-guide-source/addon-development/tutorials/tutorials.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-32 - new tutorials listing page for the new structure doc/dev-guide-source/addon-development/two-types-of-scripts.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-34 - update links doc/dev-guide-source/addon-development/xul-migration.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-35 - update links doc/dev-guide-source/module-development/chrome.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-39 - mark 'chome authority' as experimental, since we're retiring the "internals guide" division doc/dev-guide-source/welcome.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-44 - rewrite welcome page to list tutorials doc/static-files/base.html https://github.com/mozilla/addon-sdk/pull/347/files#diff-45 - simplify sidebar doc/static-files/css/sdk-docs.css https://github.com/mozilla/addon-sdk/pull/347/files#diff-46 - style changes doc/static-files/js/main.js https://github.com/mozilla/addon-sdk/pull/347/files#diff-47 - remove highlighting in sidebar, add conditional display of third-party module section doc/static-files/syntaxhighlighter/styles/shThemeDefault.css https://github.com/mozilla/addon-sdk/pull/347/files#diff-55 - style update: make code background match PRE background packages/addon-kit/package.json https://github.com/mozilla/addon-sdk/pull/347/files#diff-56 - add a keyword to addon-kit so we can recognize third-party modules packages/api-utils/docs/memory.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-58 - update link packages/test-harness/README.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-59 - update link packages/test-harness/docs/run-tests.md https://github.com/mozilla/addon-sdk/pull/347/files#diff-60 - update link python-lib/cuddlefish/docs/webdocs.py https://github.com/mozilla/addon-sdk/pull/347/files#diff-61 - add code to recognize and render third-party packages python-lib/cuddlefish/tests/static-files/doc/static-files/base.html https://github.com/mozilla/addon-sdk/pull/347/files#diff-62 - update the base.html used for testing: this file must roughly track the "real" base.html in order for the doc tests to work properly
Attachment #603403 - Flags: review?(dcm)
(In reply to Jeff Balogh (:jbalogh) from comment #2) > (In reply to Will Bamberg [:wbamberg] from comment #1) > > I've been working on trying to improve this. I'd like to know how much you > > think it helps: http://members.shaw.ca/vill/docs/sdk/wip/. > > That's looking a lot better! > > I would drop the border + background color on the h2s. It gets distracting. Do you think I should do this for all the H2s, or only for H2s in pages that are big lists of links? That is, should I drop the border and background for pages like this: http://members.shaw.ca/vill/docs/sdk/wip/dev-guide/addon-development/installation.html or only for pages like this: http://members.shaw.ca/vill/docs/sdk/wip/dev-guide/addon-development/tutorials/tutorials.html It seems to me that the border and background makes articles more scannable, but if I'm in a minority here I'll remove them.
(In reply to Will Bamberg [:wbamberg] from comment #8) > (In reply to Jeff Balogh (:jbalogh) from comment #2) > > (In reply to Will Bamberg [:wbamberg] from comment #1) > > > I've been working on trying to improve this. I'd like to know how much you > > > think it helps: http://members.shaw.ca/vill/docs/sdk/wip/. > > > > That's looking a lot better! > > > > I would drop the border + background color on the h2s. It gets distracting. > > Do you think I should do this for all the H2s, or only for H2s in pages that > are big lists of links? I'm not an expert on this, so I looked at the Django[1] and Python[2] docs. Django just uses typography and it seems scannable to me. The Python docs have a background + border around their h2s, but I don't mind it at all. I think it helps that the Python borders are only a light border-bottom and nothing on top, and they don't look boxy since they flow into the sidebar. I think dropping the borders would be better for the sdk docs. [1]: https://docs.djangoproject.com/en/1.3/ref/models/querysets/ [2]: http://docs.python.org/library/logging.html
I also enjoy the page table of contents in the sidebars of the Django and Python docs. It helps me figure out what's available on the page really fast.
Depends on: 616640
Comment on attachment 603403 [details] Link to pull request 347 I'm giving this a r+ but I do have a few things that caught my eye listed below. I don't think we need to hold back for these things as this is a very dynamic document anyway. It can certainly be iterated upon after shipping. Overall the new layout is superb. This has grown from very good and helpful documentation, to *excellent* documentation. Here are the few items I have: * While I absolutely love the landing page and how accessible everything is, I wish the big blue boxes would go away - they stand out too much... and boxes are never Tufte approved! ;) Also, I feel like all of these sections will grow in time and I think you need to tighten up the white-space a bunch. Have a look at the facebook api docs for an example of what I mean: https://developers.facebook.com/docs/ - and yes, I even like on the fb docs that each item has a simple explanation of what is waiting after the reader clicks. * I worry a bit about the order of things in the left-hand nav. Perhaps it would be good to add some collapsing on at least the low-level APIs with some arrows ^ > that allows the user to expand. What is happening is that the tools reference is waaaaay down below... so far down that I find I don't even want to scroll that far - I would even consider that for the high-level APIs at some point too. In addition, you could add "High Level API Reference" (and low level) to the landing page in-line with all the other items listed there. Make redundant navigation. * Actually, it might also be nice to move the tools reference up. At least the cfx section is pretty dang important for most folks. Again, I would add these to one of the main sections on the home page as well. Redundant! * I did notice at least one place where you had a command for people to run in terminal. I believe it was "~/mozilla/addon-sdk > cfx" - there is no distinction in that that "~/mozilla/addon-sdk >" is the prompt! Most times a $ is used to signify prompt and often a different font decoration is used too. Thats probably always been there, but it stood out to me for whatever reason. * It would be nice if "Developer Guide" in the left nav linked to the "home page" when I navigate away - its a little difficult to get back. * There is also a moment of oddness when I click on Tutorials in the nav while on the home page - they are practically the same - that's fine, and I don't have a suggestion (bad Dave!) - but it is a little odd when doing so. * At some point in the future, it would be very cool to have someone else's working, published add-on (or a few) in the "Putting it all together" section. I would love that. * I watched a friend read the docs for the first time (he'd never seen the old ones either) and he was pretty sure he could start writing an add-on quickly. He seemed to navigate quite easily through it all. The only question he really had for me was "what's cfx" while he was reading the installation docs - perhaps a call-out that introduces it would be good there. Again - this is excellent! Lets ship it!
Attachment #603403 - Flags: review?(dcm) → review+
(In reply to David Mason [:dcm :dmason] from comment #11) > Comment on attachment 603403 [details] > Link to pull request 347 > > I'm giving this a r+ but I do have a few things that caught my eye listed > below. I don't think we need to hold back for these things as this is a very > dynamic document anyway. It can certainly be iterated upon after shipping. > > Overall the new layout is superb. This has grown from very good and helpful > documentation, to *excellent* documentation. > > Here are the few items I have: > > > > * While I absolutely love the landing page and how accessible everything is, > I wish the big blue boxes would go away - they stand out too much... and > boxes are never Tufte approved! ;) So... all H2 headings have a background and border, both in the articles and in these landing pages. I used to think that having them in the articles made the articles more scannable, and that style just got carried over to the landing pages. But you're the second person (out of two!) who's brought this up. One option is to remove background and border just for H2s in the landing pages, another is to remove them for all H2 headings. Experimenting now with ditching the background and border for all H2 headings, I think the articles are just as scannable. So they're history! > Also, I feel like all of these sections > will grow in time and I think you need to tighten up the white-space a > bunch. Have a look at the facebook api docs for an example of what I mean: > https://developers.facebook.com/docs/ - and yes, I even like on the fb docs > that each item has a simple explanation of what is waiting after the reader > clicks. > * I worry a bit about the order of things in the left-hand nav. Perhaps it > would be good to add some collapsing on at least the low-level APIs with > some arrows ^ > that allows the user to expand. What is happening is that > the tools reference is waaaaay down below... so far down that I find I don't > even want to scroll that far - I would even consider that for the high-level > APIs at some point too. I'm not sure about this. I'm quite resistant to collapsing stuff. In the old style most sections were hidden by default, and it confused people. Perhaps just because the cues that stuff was hidden weren't there, but I like the simplicity of a sidebar whose content never changes. I agree that the tools reference is way down there, and that's a bit of a problem. Putting a redundant link from the main landing page would help. Moving it up would help too, I'll see what it looks like, but I think the "High-Level APIs" should come first, and then it's weird to have "Tools" in between that and "Low-Level APIs". I'll experiment, but the final fix for this might have to wait. > In addition, you could add "High Level API > Reference" (and low level) to the landing page in-line with all the other > items listed there. Make redundant navigation. > > * Actually, it might also be nice to move the tools reference up. At least > the cfx section is pretty dang important for most folks. Again, I would add > these to one of the main sections on the home page as well. Redundant! Yeah, I didn't actually give much thought to the main landing page :-/, I just duplicated the tutorials page, and it's not a great idea. I think it's confusing that it looks just like the Tutorials page, and problematic that it doesn't highlight anything else (concept guides or API ref). I will perhaps redo it and ask for another look, if that's OK. > * I did notice at least one place where you had a command for people to run > in terminal. I believe it was "~/mozilla/addon-sdk > cfx" - there is no > distinction in that that "~/mozilla/addon-sdk >" is the prompt! Most times a > $ is used to signify prompt and often a different font decoration is used > too. Thats probably always been there, but it stood out to me for whatever > reason. Under "Installation/Sanity Check"? Yeah, that's a bug, commands should not have prompts. I'll fix that in this patch. > * It would be nice if "Developer Guide" in the left nav linked to the "home > page" when I navigate away - its a little difficult to get back. > > * There is also a moment of oddness when I click on Tutorials in the nav > while on the home page - they are practically the same - that's fine, and I > don't have a suggestion (bad Dave!) - but it is a little odd when doing so. I agree, and this goes back to reworking the main landing page a bit. > * At some point in the future, it would be very cool to have someone else's > working, published add-on (or a few) in the "Putting it all together" > section. I would love that. > > * I watched a friend read the docs for the first time (he'd never seen the > old ones either) and he was pretty sure he could start writing an add-on > quickly. He seemed to navigate quite easily through it all. The only > question he really had for me was "what's cfx" while he was reading the > installation docs - perhaps a call-out that introduces it would be good > there. Thanks for the usability test! > Again - this is excellent! Lets ship it!
Forgot to mention the bug number in the merge commit message, so gitbot didn't post in here for me. Cherry-picked to stabilization in https://github.com/mozilla/addon-sdk/commit/258cf00fb6aa8486b8ac6e52ee055cde869b10ec
Status: NEW → RESOLVED
Closed: 14 years ago
Resolution: --- → FIXED
You need to log in before you can comment on or make changes to this bug.

Attachment

General

Creator:
Created:
Updated:
Size: