Page MenuHomePhabricator

Developer Documentation session at 2015 MediaWiki Developer Summit
Closed, ResolvedPublic

Description

https://www.mediawiki.org/wiki/MediaWiki_Developer_Summit_2015#Schedule
Monday 26 January 3:30 Conference Room 2

Etherpad
@Spage is organizing this

Links

interactive examples:

Conclusions

  • The audience likes the idea of generated doc more than they use it.
  • There's still a role for on-wiki documentation. Details of how to do something can be generated, but design and architecture work well on-wiki.
    • volunteers (Rob Church et al) wrote documentation for admin and users on-wiki. (The session isn't about user and admin documentation, and no plan to change that.)
  • A big win of documentation living with code is you -1 a patch until the same patch corrects the documentation.
    • So continue to generate documentation from source code. But also publish documentation that lives with source code.
  • Remove overlap of generated doc and wiki doc, specifically method-level documentation and API documentation.

Event Timeline

Spage created this task.Jan 7 2015, 7:14 PM
Spage claimed this task.
Spage raised the priority of this task from to Normal.
Spage updated the task description. (Show Details)
Spage added a subscriber: Spage.
Spage updated the task description. (Show Details)Jan 7 2015, 9:26 PM
Spage set Security to None.

See also "SOA proliferation through specification" in https://phabricator.wikimedia.org/T86028. James is planning to talk about our use of Swagger API specs for configuration, documentation, sandboxing & testing in restbase.

At first I thought this is about user documentation, but it seems it is about developer documentation. Is that correct? They are quite different things.

For developer documentation, I would like to have a way for extensions to have same kind of documentation as core generated automatically and found in same places.

Qgil renamed this task from Documentation session at #MWDS15 to Developer Documentation session at #MWDS15.Jan 14 2015, 1:22 PM
Qgil added a project: Web-APIs-Hub.
MZMcBride renamed this task from Developer Documentation session at #MWDS15 to Developer Documentation session at 2015 MediaWiki Developer Summit.Jan 14 2015, 10:39 PM
MZMcBride added a subscriber: MZMcBride.
Spage added a comment.EditedJan 15 2015, 2:21 AM

At first I thought this is about user documentation, but it seems it is about developer documentation. Is that correct?

Yes, thanks Quim and MZ for renaming. Developer documentation at developer summit.

For developer documentation, I would like to have a way for extensions to have same kind of documentation as core generated automatically and found in same places.

A few extensions are doing this, e.g. MultiMediaViewer. I only see extensions doing it for their JS with JSDuck (see config), but CSS doc with KSS and PHP doc with doxygen are probably doable as well. Meanwhile mediawiki-mirror on tool labsseems to generate PHP doc for all extensions.

It's a good topic for the session, I hope you can come.

Spage updated the task description. (Show Details)Jan 15 2015, 2:24 AM
Spage updated the task description. (Show Details)Jan 26 2015, 5:15 PM
Qgil added a subscriber: Qgil.Jan 27 2015, 7:02 AM

Please update the description with the achievements of this session. Thank you in advance.

Spage updated the task description. (Show Details)Feb 2 2015, 8:30 PM
Spage closed this task as Resolved.Feb 3 2015, 2:33 AM

Closing. I'll create backlog items for some unrelated good ideas in the Etherpad.

Spage updated the task description. (Show Details)Feb 18 2015, 6:18 AM