Documentation Draft

[Aza]

Hey Everyone,

Kurt Cagle has been working on whipping our documentation into shape. He's got a rough draft of how the editing process/markup will look. It's looking mighty fine — pretty much a JSON format.

Take a look here: https://developer.mozilla.org/en/Jetpack/UI/Wiki_Test_Page and click the edit button.

The visuals styles haven't been touched yet (so we know it's broken) but do please give feedback on the format. We know that we will be changing the particulars of the JSON format, but thoughts on how would be most welcome!

-- aza | ɐzɐ --

[Drew]

I really like being able to write docs in a simple structured format and
press a button and have them come out pretty, especially since DekiWiki
suuu-hucks. In fact I spent like a day writing a template that looks
similar to these, but I never really used it because I still had to
either use the lame-o WYSIWYG editor when filling in the template or
switch to source mode and have DekiWiki insert arbitrary HTML when I
switched back or saved, and I couldn't make the template expressive or
easy-to-use enough to include arbitrary content, like examples, styled
notes, and links.

Like:

constructorDescr:"This is the full constructor for the <b>Menu</b>
object. By providing both a label and action, this constructor will
create a menu that, when pressed, will automatically launch an action.",

How would I insert some example code here?

Drew

> --
>
> You received this message because you are subscribed to the Google
> Groups "mozilla-labs-jetpack" group.
> To post to this group, send email to mozilla-la...@googlegroups.com.
> To unsubscribe from this group, send email to
> mozilla-labs-jet...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/mozilla-labs-jetpack?hl=.

[Kurt_Cagle]

Drew,

I'm working on the example components now, (and yes, my opinion of
DekiWiki echoes yours - I was up until about 3am trying to figure out
how to get arbitrary text working).

For now - until I can figure out something better - to enter in
arbitrary markup in your text you will need to enclose everything with
string delimiters. I'm thinking as a temporary solution setting up a
couple of utility pages that will let you push a magic button that
will let you replace the edit content with appropriate safe content,
so that you don't have to lose out on having both string delimiters
available. I'll add that to my to do list, as it's an obvious
deficiency. At least for now, however, you should be able to place
markup in any of the description fields.

-- Kurt

On Nov 20, 5:28 pm, Drew <a...@mozilla.com> wrote:
> I really like being able to write docs in a simple structured format and
> press a button and have them come out pretty, especially since DekiWiki
> suuu-hucks.  In fact I spent like a day writing a template that looks
> similar to these, but I never really used it because I still had to
> either use the lame-o WYSIWYG editor when filling in the template or
> switch to source mode and have DekiWiki insert arbitrary HTML when I
> switched back or saved, and I couldn't make the template expressive or
> easy-to-use enough to include arbitrary content, like examples, styled
> notes, and links.
>
> Like:
>
> constructorDescr:"This is the full constructor for the <b>Menu</b>
> object. By providing both a label and action, this constructor will
> create a menu that, when pressed, will automatically  launch an action.",
>
> How would I insert some example code here?
>
> Drew
>
> On 11/20/09 5:02 PM, Aza wrote:
>
> > Hey Everyone,
>
> > Kurt Cagle has been working on whipping our documentation into shape.
> > He's got a rough draft of how the editing process/markup will look. It's
> > looking mighty fine — pretty much a JSON format.
>
> > Take a look here:

> >https://developer.mozilla.org/en/Jetpack/UI/Wiki_Test_Pageand click the

[Myk Melez]

On 11/20/2009 05:02 PM, Aza wrote:
> Kurt Cagle has been working on whipping our documentation into shape.
> He's got a rough draft of how the editing process/markup will look.
> It's looking mighty fine — pretty much a JSON format.

Wikis suck, but their low barrier to entry makes it so much easier for
folks to contribute to documentation that I think we would be better off
using regular wiki pages than a specialized format from which we
generate the docs.

-myk

[Aza]

Unfortunately, DekiWiki doesn't support any standard wiki-markup. That means the choice is to (1) use the raw HTML editor (which negates all the benefits of low-barrier), or (2) use the WSYWIG (which much of the Jetpack team has devolved to name-calling against).

A minimal markup scheme in the wiki, which is understandable from the get-go seems to be in order.

-- aza | ɐzɐ --

[Myk Melez]

On 11/23/2009 01:19 PM, Aza wrote:
> Unfortunately, DekiWiki doesn't support any standard wiki-markup. That
> means the choice is to (1) use the raw HTML editor (which negates all
> the benefits of low-barrier), or (2) use the WSYWIG (which much of the
> Jetpack team has devolved to name-calling against).

I have lots of names to call Deski's WYSIWYG mode too, but in the long
run it'll improve the editability of the docs to broader-enough audience
of potential contributors that it's worth the pain.

And those of us who prefer to edit the docs in a more structured format
can always switch to the raw HTML mode, which is admittedly not as good
as a JSON format but still better than the WYSIWYG mode.

-myk

[Kurt Cagle]

Myk,

I think your point is well taken, which is why I wouldn't recommend this for everything, but if we can effectively standardize on an internal set of JSON formats, it will make both CSS and linking consistent between pages, which matters more for the API Pages than it does most of the rest of the site. It also makes it much easier to make broad, systemic changes in both the layout and the structural CSS without forcing a radical redesign of each individual page. The JP_APIPage is a template that also invokes other templates. This means that if I make a change in, say, a property bag attribute associated with a given method or constructor, then this change gets propagated throughout the page. Similarly, I can add a table interface into a method for such a bag, rather than go with (or in addition to) a list interface, and anything that inherits from the JP_Method template would incorporate the changes (I'm in the process of doing this at the moment, which is why I bring it up).

I'm going with a JSON interface because it is likely that anyone writing a JetPack will be familiar with that notation, because it is easy to document, and because it is portable. I'm trying to make sure that there's still enough flexibility that you can add in whole books of content if necessary using raw HTML content - which is actually better than I think what DekiWiki provides now in its own editor (if you're in raw mode, trying to write complex HTML can prove difficult because of the fairly nonintuitive manner in which it parses internal HTML or XML content).

Worst case scenario, we can use this as a foundation to generate the core content then copy this content to final deployment, making changes as necessary. We lose inheritance that way, but it can at least simplify the development process.

Kurt Cagle

-myk