New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Centralize all the documentation and decide for a system #2503

Open
cmfcmf opened this Issue Jun 20, 2015 · 10 comments

Comments

Projects
None yet
3 participants
@cmfcmf
Member

cmfcmf commented Jun 20, 2015

We need to centralize all the Zikula documentation and decide for a common language / markup to convert it to.

Places where documentation is currently:

Possible markups / systems to use

Place Markup + -
GitHub Wiki Markdown, AsciiDoc, ReStructuredText no need for extra servers / scripts not that flexible, everyone can edit without further notice
Separate repository (zikula/zikula-docs) reStructuredText very flexible, used by Symfony, embeddable into zikula.org, not too easy to write need for an extra server / script / module to compile and display it

Feel free to add to the list of possibilities.

@cmfcmf cmfcmf added this to the Future Ideas milestone Jun 20, 2015

@craigh

This comment has been minimized.

Show comment
Hide comment
@craigh

craigh Jun 20, 2015

Member

👍

Member

craigh commented Jun 20, 2015

👍

@craigh

This comment has been minimized.

Show comment
Hide comment
@craigh

craigh Jun 20, 2015

Member

also - need to figure out a way to post it to zikula.org (oh, now I read you said that already)

Member

craigh commented Jun 20, 2015

also - need to figure out a way to post it to zikula.org (oh, now I read you said that already)

@craigh

This comment has been minimized.

Show comment
Hide comment
@craigh

craigh Jul 19, 2015

Member

The docs must be version-able somehow. Investigate how symfony does this.

much of our documentation will be pointing to third party docs, e.g. Doctrine, Symfony, etc

Member

craigh commented Jul 19, 2015

The docs must be version-able somehow. Investigate how symfony does this.

much of our documentation will be pointing to third party docs, e.g. Doctrine, Symfony, etc

@craigh

This comment has been minimized.

Show comment
Hide comment
Member

craigh commented Jul 21, 2016

@cmfcmf

This comment has been minimized.

Show comment
Hide comment
@cmfcmf

cmfcmf Jul 21, 2016

Member

http://stackoverflow.com/tour/documentation

The issue is that the zikula tag at StackOverflow isn't active enough to allow documentation.

http://stackoverflow.com/documentation/zikula/commit

Member

cmfcmf commented Jul 21, 2016

http://stackoverflow.com/tour/documentation

The issue is that the zikula tag at StackOverflow isn't active enough to allow documentation.

http://stackoverflow.com/documentation/zikula/commit

@craigh

This comment has been minimized.

Show comment
Hide comment
@craigh

craigh Jul 21, 2016

Member

agreed. That could change though if we desired it I think.

Member

craigh commented Jul 21, 2016

agreed. That could change though if we desired it I think.

@Guite

This comment has been minimized.

Show comment
Hide comment
@Guite

Guite Oct 28, 2016

Member

@cmfcmf why is an extra repository embeddable into zikula.org, but the GitHub wiki not? A GitHub wiki is also a git repository. You can for example do git clone git@github.com:zikula/core.wiki.git.

Member

Guite commented Oct 28, 2016

@cmfcmf why is an extra repository embeddable into zikula.org, but the GitHub wiki not? A GitHub wiki is also a git repository. You can for example do git clone git@github.com:zikula/core.wiki.git.

@cmfcmf

This comment has been minimized.

Show comment
Hide comment
@cmfcmf

cmfcmf Oct 28, 2016

Member

@cmfcmf why is an extra repository embeddable into zikula.org, but the GitHub wiki not? A GitHub wiki is also a git repository. You can for example do git clone git@github.com:zikula/core.wiki.git.

sure.

Member

cmfcmf commented Oct 28, 2016

@cmfcmf why is an extra repository embeddable into zikula.org, but the GitHub wiki not? A GitHub wiki is also a git repository. You can for example do git clone git@github.com:zikula/core.wiki.git.

sure.

@Guite

This comment has been minimized.

Show comment
Hide comment
@Guite

Guite Dec 6, 2016

Member

Last week I talked with @rallek about user docs and we agreed that it would be advantageous to have these directly inside the application instead of separate documents.

How about this (again, for user docs):

Step 1:

  • establish a structure for module-based documentation in Markdown format (this should consider the possibility to add translations)
  • automatically provide a help or manual link in the admin menu of a module (similar to the hooks link) if Markdown files are available (could be exposed using a capability to avoid file system scans); use markdown parser to display the docs in html
  • default way to show this documentation, for example using a modal window or a sidebar (like mmenu, but on the right side)

Step 2:

  • maybe implement an additional functionality to create a complete manual by combining the markdown files of all available modules into one document (whereby each extension and theme are included as a sub chapter)
  • possibility to create pdf files for single extensions or the complete manual

Benefits:

  • documentation is maintained directly with the component instead of elsewhere
  • context sensitive: users find documentation right at the page where they need it
  • easy to handle for different versions (documentation is updated together with the code)
  • easy to avoid that docs become outdated
  • easy way to contribute as Markdown is simple
  • easy to translate
  • possibility to create a central documentation automatically (using CI) to publish it on zikula.org for example

Aspects to think about:

  • updating translations: maybe we can/should use gettext or something else so that updates can be reflected into existing translations without having to review everything again and again
  • deep links between the docs of different extensions (e.g. link a doc section of AdminModule inside the docs of FormiculaModule)
Member

Guite commented Dec 6, 2016

Last week I talked with @rallek about user docs and we agreed that it would be advantageous to have these directly inside the application instead of separate documents.

How about this (again, for user docs):

Step 1:

  • establish a structure for module-based documentation in Markdown format (this should consider the possibility to add translations)
  • automatically provide a help or manual link in the admin menu of a module (similar to the hooks link) if Markdown files are available (could be exposed using a capability to avoid file system scans); use markdown parser to display the docs in html
  • default way to show this documentation, for example using a modal window or a sidebar (like mmenu, but on the right side)

Step 2:

  • maybe implement an additional functionality to create a complete manual by combining the markdown files of all available modules into one document (whereby each extension and theme are included as a sub chapter)
  • possibility to create pdf files for single extensions or the complete manual

Benefits:

  • documentation is maintained directly with the component instead of elsewhere
  • context sensitive: users find documentation right at the page where they need it
  • easy to handle for different versions (documentation is updated together with the code)
  • easy to avoid that docs become outdated
  • easy way to contribute as Markdown is simple
  • easy to translate
  • possibility to create a central documentation automatically (using CI) to publish it on zikula.org for example

Aspects to think about:

  • updating translations: maybe we can/should use gettext or something else so that updates can be reflected into existing translations without having to review everything again and again
  • deep links between the docs of different extensions (e.g. link a doc section of AdminModule inside the docs of FormiculaModule)
@craigh

This comment has been minimized.

Show comment
Hide comment
@craigh

craigh Dec 6, 2016

Member

sounds like https://github.com/craigh/DocTastic which I started and abandoned years ago.

Member

craigh commented Dec 6, 2016

sounds like https://github.com/craigh/DocTastic which I started and abandoned years ago.

@craigh craigh removed meta labels Apr 2, 2017

@craigh craigh added the Documentation label Jul 2, 2017

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment