Documenter

[nilshoerrmann]

I'm not sure if this is the right place (I'm not sure if this is even the right repository), but it would be nice if the new Symphony documentation could be integrated with Documenter. I'm thinking of some kind of default documentation that Documenter provides based on the Symphony website or a Github repository (depends on the way the docs will be stored, static Markdown files would be great).

/cc @johannahoerrmann @bauhouse

[ranbureand]

Yesterday, while editing the current content structure of the Docs, I thought providing some very simple and short directions to authors (not builders nor developers) using the back end interface of a Symphony installation for the very first time could be a good idea, since it could potentially spare the time builders/developers spend to teach authors how to use it.

Deploying such directions via Documenter could be a nice option.

[johannahoerrmann]

providing some very simple and short directions to authors

@theBigMandarino, this is how we have been using Documenter for the last 3 years and it has been tremendously helpful indeed, both for us and for our client! Markdown syntax, where to change your password, you name it - see https://github.com/hananils/pompodium for our latest use case.

some kind of default documentation

It would be awesome to see a list of (all the?) topics relevant to the area I'm viewing (Data Sources, Pages, Sections …) in the Documenter. Fantastic!

[bauhouse]

@nilshoerrmann, yes, this is the right repository. And we are thinking about storing the docs as static Markdown files. Integrating Documenter sounds like a great idea! I am anxious to try out the new Pompodium release to see how you're using the Documenter extension. @johannahoerrmann, as you have been using Documenter for the last 3 years, it will be good to be using something that has been put through its paces for that long.

[nilshoerrmann]

yes, this is the right repository.

Maybe we could clean up the @symphonycms repositories a bit. There are just so many ...

And we are thinking about storing the docs as static Markdown files.

That's great! Documenter is currently storing everything in the database but we would like to change this to a filebased approach so that site documentation can be tracked with Git and can be shared across installs easily. The only reason we didn't implement it yet is that we didn't know how to keep files and database in sync. But maybe it would be just okay to convert the Markdown files on the fly, they are normally not that long.

[nilshoerrmann]

Some thoughts on Documenter: https://gist.github.com/nilshoerrmann/6260980

[ijy]

That's a great idea! I can certainly see how it would be useful to provide clients at least with readily available documentation in the control panel. And I completely agree that it's far better to store these as markdown files on the filesystem rather than in the database. On the fly conversion rather than a DB sync should be all that's needed.

Being an extension is good too so it's not forced upon users if they choose not to make documentation available.

I haven't used Documenter yet but I'll install it and give it a go to get a feel for it.

[ranbureand]

@nilshoerrmann and @johannahoerrmann, I just had a look at the use case of Documenter in Pompodium and it’s really a gem!

Thinking out loud: so in the end the documentation handled via Documenter could be of two kinds: a basic general one, explaining how to use the standard areas of the back end interface of a Symphony installation (Blueprints: Pages, Sections, Data Sources, … / System: Authors, Preferences, …) to authors/builders/developers, and a specific one, explaining how to use the “ad hoc” crafted areas (Navigation group/s, ../publish/*).

The former could be provided by default after Documenter has been successfully installed, while it would be up to the builder/developer to write the latter.

As Johanna suggests, the basic general one could provide a list to external resources contained in the Docs section of the Documentation site, which aim will be teaching the basics to new users.

[bernardodiasc]

This is still a very good idea. Any update on this topic? I haven't used Documenter for a while.

It's possible to fetch Documenter content from the docs site when installing the extension or somewhere else? for instance.

[brendo]

It's possible to fetch Documenter content from the docs site when installing the extension or somewhere else? for instance.

Not currently I don't believe. The idea of using a remote 'dictionary' or something would be pretty neat.

[bernardodiasc]

By calling with Ajax os something like that? Its possible to provide docs content in json format easily with Jekyll.

[nilshoerrmann]

There once was the idea to move Documentor entries from the database to plain Markdown. This would have allowed better sharing between sites and tracking using Git. In this context, the idea can up to provide the core documentation in Markdown files as well (through an API on the official site).

The idea was to transform all files in the browser directly using https://github.com/showdownjs/showdown.

But that was 2 years ago.