Open sandrokeil opened 8 years ago
for api docs we can use something like http://www.apigen.org/
I've thought about documentation for a while and would like to suggest a different structure:
We should focus on each component individually. It is just too much work to create all the docs in a way that they look nice together and are easy to navigate. And it is also hard to keep them in sync. Also you need to jump between components when describing advanced topics like event sourcing + event store and so on. I think it is easier to provide a walk-through guide and for details link to the component docs. All components should use the same layout, so that they look similar but the docs must not have the same structure.
Thoughts @prolic @sandrokeil @bweston92 @basz @oqq ?
I still think component docs should be on the website. If not, where then.
Am 14.01.2017 23:32 schrieb "Alexander Miertsch" notifications@github.com:
I've thought about documentation for a while and would like to suggest a different structure:
- Every package has its own documentation (mix of api docs, examples, whatever is needed for the component). We don't merge them to a global documentation.
We use the proophessor repo as a source for getprooph.org. On getprooph.org we provide the big picture:
- Nice start page
- What is prooph. which frameworks are supported, where to get started, people behind prooph, ...
- Information about long term support, commercial support, projects and people using prooph ...
- A Getting started guide
- A walk-through tutorial
- A cookbook for mixed special topics (like a small blog ...)
Why no combined documentation?
We should focus on each component individually. It is just too much work to create all the docs in a way that they look nice together and are easy to navigate. And it is also hard to keep them in sync. Also you need to jump between components when describing advanced topics like event sourcing
- event store and so on. I think it is easier to provide a walk-through guide and for details link to the component docs. All components should use the same layout, so that they look similar but the docs must not have the same structure.
Thoughts @prolic https://github.com/prolic @sandrokeil https://github.com/sandrokeil @bweston92 https://github.com/bweston92 @basz https://github.com/basz @oqq https://github.com/oqq ?
— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub https://github.com/prooph/proophessor/issues/38#issuecomment-272631223, or mute the thread https://github.com/notifications/unsubscribe-auth/AAYEvCNnGQGLNEqZaFeVI9ajOdceEhuVks5rSOqGgaJpZM4H0qEh .
https://help.github.com/articles/user-organization-and-project-pages/#project-pages
A custom domain on User and Organization Pages sites applies the same domain redirect to all Project Pages sites hosted under that account. Project Pages sites that use a custom domain are also available at username.github.io/projectname for personal accounts, and orgname.github.io/projectname for organizations.
If I understand correctly it would be possible to have https://getprooph.org/event-store So we can link to all project pages from getprooph.org but don't need to merge all docs with bookdown.
The website should have a menu: Getting Started | Components | Support | News?
Under components
we list all components and link to the project pages
then we add a home
link (on the prooph logo?) to link back to getprooph.org.
Or an skeleton site on getprooph the pulls content /structure via JavaScript from the component repositories?
@basz bookdown can pull remote docs, but the problem is, that bookdown generates a single/combined book. So we need to write documentation for a component as a chapter of that combined book this influences the headlines and the structure of the components docs. I'm not convinced that this is a good idea. However, I'm playing with the set up to see what is possible and what not. The suggestions by @sandrokeil are good, but the generated navigation is my main problem at the moment. Hosting each components docs as a separate project page would allow us to write components docs without worrying about the generated main book.
@codeliner Good idea with the walk through guide. This should give new users a better entrypoint. We can also take a look at zend framework. ;-) I guess it's a good blueprint.
With this, I also think it's better to handle the component docs individually and put a component overview to the main page.
For a good structure of the centralized documentation we should restructure component docs a bit.
I'd like to have 4 main navigation items in the central docs:
Tutorial | CQRS | Event Sourcing | Event Store
The Logo should link back to getprooph.org where users can find all information about the project prooph
Tutorial contains the walk-through guide
CQRS includes docs from prooph/service-bus Event-Sourcing points to prooph/event-sourcing Event Store points to prooph/event-store
All other components are linked from there:
So, the component bookdown.json files should be aligned in a way that they work for single component docs but also within the central docs navigation (avoid long titel, clear structure, ...)
This is an issue to discuss the documentation structure and how we can improve the documentation. The bookdown bootswatch template has a top menu and a search engine is coming with the next release. I think we must differ between component docs and whole documentation. This has some advantages and disadvantages.
Single Component docs
The structure should be equal for all components and should have at least this structure (see link above):
All component docs
I'm not sure if we can simply use the bookdown books of every component to build the whole documentation, because some restructuring could improve the docs. But it would be recommended to use the bookdown.json file of each component for the book structure to avoid maintenance if new pages are added to a component.
Here is a proposal for the structure:
We have also many adapters for different components and there are 2 possibilities:
prooph/event-store
includes also the adapters in their docs via bookdown.json file of the adapter repository (preferred)General doc improvements