Rethinking docs.services.mozilla.com

Tarek Ziade tarek at mozilla.com
Wed Jan 11 13:22:38 PST 2012


On 01/11/2012 12:41 PM, Gregory Szorc wrote:

+1 for the proposal
>
> We do lose:
>
> * Some control over the docs
> * The benefits of ReST+Sphinx
> * Complete service docs unification (except we aren't really there today)
I think this just a matter of having the proper landing page at the root 
of docs.services, that tells people where to go depending on who they 
are and what they look for.

>
> I should state that I believe the user-level docs should be separate 
> only as long as they are maintained independently of the source code. 
> If a project decides to bundle user-level docs alongside the source 
> (which has its own pros and cons), then I think docs.services is a 
> fine place to put a copy of these auto-generated docs (since we have 
> no better place to put them AFAICT). The same thing goes for any docs 
> derived from the project's source tree.
>
I'd add, if all projects use Sphinx in a docs/ directory in their repo 
it will be simple to populate and keep up-to-date a "projects" docs.services

That was one of my long term goals in docs.services

Cheers
Tarek

-- 
Tarek Ziade - Mozilla Services



More information about the Services-dev mailing list