Symphony.

While creating a dashboard for our department website I was thinking if it would be possible to integrate or at least link to the Symphony documentation to offer a new admin an easy way to understand the system.

While this could be done by hardcoded links, I was thinking if it would be a nice idea to syndicate the documentation in a public way. Given that it would be released under a Creative Commons licence (or similar) and given it would be provided as XML source it would be easily possible to integrate the content into Symphony projects.

Would that be possible? Or do you think this is stupid idea?

Did we discuss this a while back, thinking that the Documentor extension could remotely pull the docs from the Symphony site? Maybe I just discussed it in my head. It’s a neat idea, but may need an intermediary mapping layer to map a Symphony backend page to, say, a page in the Glossary docs. We shouldn’t let the backend UI structure the way the docs are written, that’s for sure.

Nick, we did discuss it. It’s always been the intention to make the docs portable by building a simple API for them. This way wherever and however they need to be used, they can be. Sounds like one for the Docs Working Group, although Nick maybe we should have a chat about finishing up that REST API extension…

Should we consider making the documentation live in its own little sub-site? One example is jQuery’s MediaWiki-based docs site.

We obviously don’t have to use MediaWiki, but it might make sense to put the docs in a place where they can be structured independently. (That way we wouldn’t have to modify the architecture of the Symphony site.)

Then if we had an API to the docs, the Symphony site could just use it to embed relevant parts of the documentation when necessary?

We’ve considered this in the past, and there are benefits, but we’ve always opted for keeping everything unified. Part of the reason is that the goal is still to enable user feedback/contribution/translation on the docs, and we don’t want to have to spread user/session info over multiple systems. Also, we didn’t want users’ experiences to be disruptive if forced to travel across two or more separate sites with slightly different navigation structures, etc.

Always happy to revisit though…

Makes sense. In any case, I guess the hard part is setting up the API and structuring the documentation so it can be retrieved predictably, which would have to be done regardless of where the docs are located.

Nick maybe we should have a chat about finishing up that REST API extension…

Yes, please! This extension excites me and I think will fit the bill nicely for documentation.

have you guys considered formatting comments in the style of phpDocumentor? this is styled after JavaDocs, and I think it would be a good way to get documentation out quicker as that is the biggest thing people ask for.

I started commenting my JS after JSDoc, and I think it’s a good way to just start documenting your code, regardless if you use the build scripts to make the actual documentation page.

@wtdtan

I believe phpDoc is planned for v3.