search

prooph / proophessor

Exploring prooph components
http://getprooph.org
BSD 3-Clause "New" or "Revised" License
85 stars 23 forks source link

New documentation structure #38

Open sandrokeil opened 8 years ago

sandrokeil commented 8 years ago

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):

| Getting Started
| -- Overview (Installation, ...)
| -- Quick Start
| Reference
| -- API (much work I guess)
| -- Examples
| Contribute
| -- Contributing
| -- Using GIT
| -- Changelog

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:

| Getting Started
| -- Overview
| -- Quick Start
| Prooph Service Bus (Command, Event, Query) (component bookdown.json)
| -- Messaging to external systems 
| ---- ZeroMQ
| ---- AMQP
| -- Plugins
| Prooph Event Sourcing (component bookdown.json)
| -- Prooph Event Store (component bookdown.json)
| -- Prooph Event Store Adapter (component bookdown.json)
| -- Prooph Snapshotter (component bookdown.json)
| Marry CQRS with Event Sourcing  (component bookdown.json)

We have also many adapters for different components and there are 2 possibilities:

  1. Main components like prooph/event-store includes also the adapters in their docs via bookdown.json file of the adapter repository (preferred)
  2. Integrate them separately in the whole docs

    General doc improvements

  3. Add new copyright
  4. Add prooph components logo
  5. Add toc depth of 2
  6. Restructure component docs as mentioned above
  7. Add list of 3rd party plugins
prolic commented 8 years ago

for api docs we can use something like http://www.apigen.org/

codeliner commented 7 years ago

I've thought about documentation for a while and would like to suggest a different structure:

  1. 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.
  2. 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 @sandrokeil @bweston92 @basz @oqq ?

prolic commented 7 years ago

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:

  1. 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.

  2. 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 .

codeliner commented 7 years ago

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.

basz commented 7 years ago

Or an skeleton site on getprooph the pulls content /structure via JavaScript from the component repositories?

codeliner commented 7 years ago

@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.

sandrokeil commented 7 years ago

@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.

codeliner commented 6 years ago

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:

prooph/service-bus

prooph/event-sourcing

prooph/event-store

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, ...)