Docs Simplification

[talsraviv]

@zekiel @moollaza @russellholt in preparation for tomorrow

What's left in order of priority - correct me otherwise:

• First Goodie walkthrough
• Screenshots
• Linking
• Index, Prev/Next
• Two more walkthroughs each for Spice, Goodie, and Cheat Sheets
• Submission Checklist (@moollaza)

Questions:

• Is Pure JS functions still relevant given Goodies have full display capabilities?
• Is the Spice JS API available to Goodie Frontends too?
• Other dev environments - what do you guys think of leaving that section behind?

Random:

• Is Spice Advanced Frontend used often? Just feels like one of those there-must-be-a-better-way things.

[russellholt]

@talsraviv You're seeing the fact that goodies and spice are slowly converging. most of the JS stuff applies to both. The global object Spice is really an alias to the global object DDH. so Spice.add() should really be DDH.add(). The main divergence is the interface, which isn't going to be addressed until the next generation of the api. for a spice that's currently the ddg_spice_* function that calls DDH.add() (formerly Spice.add), whereas for a goodie that's the DDH.X.build function which returns an object. The argument to DDH.add() for a spice, and the object returned by build for a goodie have the same format.

• Pure JS functions: somewhat relevant, but no - it's been taken over by goodies
• Spice JS API: yes, available to goodies.
• other dev environments - maybe some of that can be moved to a README.md, maybe in duckpan? I think we still need some of that but I imagine it could be reduced. It's kind of wordy. Maybe:
  • reduce Operating System notes to list the ones it's been installed on and for everything else YMMV
  • installing duckpan locally: cut out all the examples
  • shell completion: just the para + the links. So wordy; up to you.
  • the rest just goes on and on and on and on.. do we need that much detail? It's written for newbies but newbies should be using codio.
• Spice Advanced Frontend : yes, there must be a better way, but it should remain documented for now.

[talsraviv]

@zekiel @moollaza as far as submitting section the pages are:

• Intro/Quality
• Checklist
• Maintenance
• Pull request instructions

We'll discuss what's most important for each to contain on the call today with @russellholt

[talsraviv]

@russellholt @moollaza check out the last commit if you can - I want to make sure I got it right especially on the DDG/DDH/Spice namespaces.

[talsraviv]

@Eelviny @moollaza last commit incorporates your latest feedback - thanks!

[talsraviv]

@moollaza @zekiel just pushed up the submission section - take a look. I used Zaahir's checklist and tried to keep it as straightforward and focused as I could. I divided it into what I thought should be explicit and what I will work into the rest of the docs.

[talsraviv]

@moollaza btw the current docs mention checking for possibility of XSS - is that still relevant?

[talsraviv]

(In the meantime I'm also reviewing asana/github issues to keep this branch updated with suggestions, seems good for now)

[moollaza]

@moollaza btw the current docs mention checking for possibility of XSS - is that still relevant?

Yes, I just plugged an XSS issue this week. It's still required for the simple structured_answer in Goodies, and certainly possible in Spice's when using custom templates

[talsraviv]

Just a note: I've been making all changes in a temporary repo on my account to be able to stage it on gitbooks without changing the main docs: https://github.com/talsraviv/duckduckgo-documentation-gitbook