The {{draft}} macro's helpfulness

[Eric Shepherd]

We have more documentation than ever, and more of it is in various
states of construction. I increasingly find myself making use of the
draft macro in order to try to ensure that readers know a page isn't
finished. However, that banner isn't particularly helpful since it
conveys no useful information.

I would like to propose we make some enhancements to the macro to make
it more helpful.

I think it would be useful to add the option to include a brief bit of
text explaining the draft status (is it because the article is being
updated because of spec changes? is it being written actively? is it
just part of a project that needs doing but isn't being worked on?), as
well as possibly a link to the appropriate doc status page and/or a link
to help find the person heading up the doc work in that area.

This would help not only make the banner more useful, but also it would
stand out a little better so maybe it would catch people's eyes more,
preventing some misunderstandings about the quality of content.

Assuming there's some consensus that this is a good idea, there are a
couple of ways it could be done.

Obviously, it could accept optional parameters. However, I know there's
a push to try to reduce reliance on parameters for macros like these.
The other option would be to add information to the GroupData and/or
InterfaceData databases which would be used by the draft macro. Probably
just GroupData.

You should be able to build the doc status page link automatically given
the API name, correct?

After that, you add optional fields to GroupData records like this
(exact names of fields and options are TBD; this is just to give an idea
of what I'm thinking):

* "draftstatus": ["in-progress", "complete", "helpwanted", "stub"]
(maybe allow more than one of these at a time; text in the box would
be generated based on which of these are included]
* "contact": "username-of-project-lead"

These are totally ignored if the {{draft}} macro isn't used. If it is,
then the Draft banner is more informative.

Does that stir up ideas out there?

--

Eric Shepherd
Senior Technical Writer
Mozilla Developer Network <https://developer.mozilla.org/>
Blog: https://www.bitstampede.com/
Twitter: http://twitter.com/sheppy
Doodle: http://doodle.com/the.sheppy

[Sebastian Zartner]

If an article needs to be updated due to a spec. change, I'd rather add a
{{note}} and/or the NeedsUpdate tag instead of {{draft}}. In cases I need
help, I set the related review flags. And whether or not an article is
actively worked on can be checked through its revision history.
Basically I'd prefer the draft flagging to be implemented as described in bug
770390 <https://bugzilla.mozilla.org/show_bug.cgi?id=770390>.
But I understand the need for having a way to see at a glance why an
article includes a {{draft}} macro. If others think this info should be
centralized and be made more obvious, then I'd vote for allowing a string
parameter for {{draft}} for providing an advanced description (in form of a
custom string or a keyword for predefined strings).

Sebastian

> _______________________________________________
> dev-mdc mailing list
> dev...@lists.mozilla.org
> https://lists.mozilla.org/listinfo/dev-mdc
> MDN contributor guide: http://bit.ly/ContributorGuide
> Doc project Trello board: https://trello.com/b/HAhl54zz/status
>

[Chris Mills]

So I agree with Sebastian here, that there should be an optional advanced string available if you want to add a custom draft message.

I think Sheppy’s thoughts make sense for draft API docs, but we need to consider that there are different types of docs that we might need the draft macro for. Perhaps we should have a type parameter too, to specify what type of doc we are adding the draft macro to?

E.g. generic, apiref, guide, otherref, custom or whatever else we need?

{{draft(‘generic')}} could be the default, be synonymous with just {{draft}}, and give us the current message, for backward compatibilty’s sake

{{draft(‘custom’, ‘my custom draft message')}} could give us a custom draft message, like the one sebastian was talking about.

{{draft(‘apiref’, ‘IndexedDB')}} (for example) could make a call into GroupData like Sheppy was talking about, and result in a message such as

“Draft: This page of the IndexedDB API documentation is in progress. If you want to help or have feedback, contact the project owner, Chris Mills.”

{{draft(‘guide’, ‘’, … )}} could result in something else.

or whatever.

Is this overthinking it too much? ;-)

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[Sebastian Zartner]

Note that the type and item you are discribing could be automatically
determined by the macro via analyzing the URL it is used on.
E.g. using {{draft}} (without parameters) on
https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API, the macro
would know that it needs to display the hint related to the IndexedDB API.
I used a similar approach for {{cssinfo}} and {{csssyntax}}.
Custom strings could then be added using {{draft('My custom draft
message')}} and predefined ones using
{{draft('special_draft_message_l10n_key')}}.

Sebastian

[Chris Mills]

Good point - this would make the whole thing simpler.

Chris Mills
Senior tech writer || Mozilla
developer.mozilla.org || MDN
cmi...@mozilla.com || @chrisdavidmills

[Eric Shepherd]

Right; that's why my proposal was as simple as it was, eschewing all
parameters entirely.

But yes, I would be fine with a custom message parameter.

The question becomes whether to simply allow you to specify a custom
message, or whether to dive deeper and automatically pull out and add
more information.

Of course, we can start with just a custom message parameter, and then
investigate adding support for more stuff later, since that would come
from GroupData, the URL, and other sources and not require parameters,
at least in theory.

> Note that the type and item you are discribing could be automatically
> determined by the macro via analyzing the URL it is used on.
> E.g. using {{draft}} (without parameters) on
> https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API, the
> macro would know that it needs to display the hint related to the
> IndexedDB API.
> I used a similar approach for {{cssinfo}} and {{csssyntax}}.
> Custom strings could then be added using {{draft('My custom draft
> message')}} and predefined ones using
> {{draft('special_draft_message_l10n_key')}}.

[Eric Shepherd]

OK. I'm going ahead and adding a parameter to {{draft}} to accept a
string to add to the box. We can look into adding details to the
GroupData to be pulled out by {{draft}} at a later date.

> Of course, we can start with just a custom message parameter, and then
> investigate adding support for more stuff later, since that would come
> from GroupData, the URL, and other sources and not require parameters,
> at least in theory.

[Eric Shepherd]

And I've now done this.
https://developer.mozilla.org/en-US/docs/Template:draft

> OK. I'm going ahead and adding a parameter to {{draft}} to accept a
> string to add to the box. We can look into adding details to the
> GroupData to be pulled out by {{draft}} at a later date.