Rework the Index and Quick Start guide #24

settermjd · 2020-09-16T20:37:26Z

Q	A
Documentation	yes
Bugfix	no
BC Break	no
New Feature	no
RFC	no
QA	no

Description

This intent of this PR isn't to turn the documentation into a marketing piece, rather ensure that it is a succinct, yet also sufficiently descriptive, introduction to what laminas-hydrator is. It's aimed at helping people who are seeing the package/component for the first time and need to quickly know what it is, and what they can do with it, and gives
them an incentive to delve deeper.

It:

Updates the package description to provide a more thorough introduction to the package
Reworks the Quick Start guide as follows:

Updates the introductory content to build upon the core description in index.md. This time, the user is a step deeper and seeking to learn more. So this description takes them that bit deeper, providing them quick and easy access to the next level down into the component.
Brings the usage section right up near the top, so that they can get a sample of how the package works and what they can expect.
Moves the available implementations to after the usage section, simplifies the headers and descriptions of each one, and adds a usage example for any that don't have one. The reason for this is that, to me, using the FQN as the section header is redundant and too verbose. The descriptions were reworked to read a little more like a narrative, yet still maintain the focus of a core documentation guide. I tried hard to make the text flow, yet still, be active and to the point. There should be usage examples for each one, as you can never be sure which one the user may be most interested in, which one they need, and for completeness sake. I also sorted the hydrators into what seemed to be the most applicable order of complexity, from the most basic to the most advanced.

I need to check the usage examples for accuracy. After that, I'll remove the draft status.

froschdesign

The page should be modified consistently and should show only a quick start. Everything else should be listed separately.

docs/book/index.html

docs/book/v3/quick-start.md

mkdocs.yml

docs/book/v3/quick-start.md

settermjd · 2020-09-23T19:03:24Z

@froschdesign, what do you think of the state of the PR as it currently stands?

froschdesign

Only some small corrections.

froschdesign · 2020-09-23T19:08:22Z

composer.json

@@ -1,6 +1,6 @@
 {
    "name": "laminas/laminas-hydrator",
-    "description": "Serialize objects to arrays, and vice versa",
+    "description": "laminas-hydrator provides functionality for hydrating objects and extracting data from them. The component contains concrete implementations for a number of common use cases and provides interfaces for creating custom implementations.",


Please revert this. We can find a shorter description in another pull request and add this sentence to the introduction also in another pull request.

froschdesign · 2020-09-23T19:10:19Z

docs/book/v3/quick-start.md

+use Laminas\Hydrator;

-interface ExtractionInterface
-{
-    /**
-     * Extract values from an object
-     *
-     * @return mixed[]
-     */
-    public function extract(object $object) : array;
-}
+$hydrator = new Hydrator\ArraySerializableHydrator();


Can be written in one line because the namespace is only used once:

$hydrator = new Laminas\Hydrator\ArraySerializableHydrator();

froschdesign · 2020-09-23T19:10:40Z

docs/book/v3/quick-start.md

+use Laminas\Hydrator;

-interface HydrationInterface
-{
-    /**
-     * Hydrate $object with the provided $data.
-     *
-     * @param mixed[] $data
-     * @return object The implementation should return an object of any type.
-     *     By purposely omitting the return type from the signature,
-     *     implementations may choose to specify a more specific type.
-     */
-    public function hydrate(array $data, object $object);
-}
+$hydrator = new Hydrator\ArraySerializableHydrator();


Can be written in one line:

$hydrator = new Laminas\Hydrator\ArraySerializableHydrator();

froschdesign · 2020-09-23T19:11:21Z

docs/book/v3/quick-start.md


 ```php
-namespace Laminas\Hydrator;
+<?php


Please remove the open tag.

froschdesign · 2020-09-23T19:11:55Z

docs/book/v3/quick-start.md

-interface HydratorInterface extends
-    ExtractionInterface,
-    HydrationInterface
+use Laminas\Hydrator;


The same like before, the namespace is used only once therefore it can be reduced on one line.

docs/book/v3/quick-start.md

mkdocs.yml

froschdesign · 2020-09-23T19:22:55Z

@settermjd
I added all open tasks to a project: https://github.com/laminas/laminas-hydrator/projects/1

The intent here isn't to make this in to a marketing piece, rather to provide a succinct, yet also sufficiently descriptive snapshot overview/introduction to what laminas-hydrator is. It's aimed at people who are seeing the package/component for the first time and need to quickly know what it is. I hope that this change does that, and gives them incentive to delve deeper. Signed-off-by: Matthew Setter <[email protected]>

The intent of this change is to make the content far more accessible to first time readers. The changes include: 1. Update the introductory content to build upon the core description in index.md. This time, the user is a step deeper, and seeking to learn more. So this description takes them that bit deeper, providing them quick and easy access to the next level down in to the component. 2. As they're still new to the package, it brings the usage section right up near the top, so that they can get a sample of how the package works and what they can expect. 3. It moves the available implementations to after the usage section, simplifies the headers and descriptions of each one, and adds a usage example for any that don't have one. The reason for this is that, to me, using the FQN as the section header is redundant and too verbose. The descriptions were reworked to read a little more like a narrative, yet still maintain the focus of a core documentation guide. I tried hard to make the text flow, yet still be active and to the point. There should be usage examples for each one, as you can never be sure which one the user may be most interested in, which one they need, and for completeness sake. I also sorted the hydrators in to what seemed to be the most applicable order of complexity, from the most basic to the most advanced. Signed-off-by: Matthew Setter <[email protected]>

Signed-off-by: Matthew Setter <[email protected]>

@froschdesign

This patch incorporates feedback as provided by @froschdesign. Signed-off-by: Matthew Weier O'Phinney <[email protected]>

settermjd added Documentation Enhancement Review Needed labels Sep 16, 2020

settermjd requested review from froschdesign and michalbundyra September 16, 2020 20:37

settermjd self-assigned this Sep 16, 2020

froschdesign requested changes Sep 17, 2020

View reviewed changes

settermjd marked this pull request as ready for review September 21, 2020 17:10

settermjd force-pushed the update-index-and-quick-start-guide branch from 7238913 to 6b1de29 Compare September 22, 2020 18:01

froschdesign requested changes Sep 23, 2020

View reviewed changes

weierophinney changed the base branch from 3.2.x to 3.1.x October 6, 2020 14:43

settermjd added 7 commits October 6, 2020 09:44

Update the project description to match the mkdocs change

2409f51

Signed-off-by: Matthew Setter <[email protected]>

Remove redundant content and correct some headers

1e25905

Signed-off-by: Matthew Setter <[email protected]>

Revert unnecessary change to docs/book/index.html

919d47f

Signed-off-by: Matthew Setter <[email protected]>

Fix up errors in the code examples

aa106c9

Signed-off-by: Matthew Setter <[email protected]>

Remove unnecessary anchors

e931241

Signed-off-by: Matthew Setter <[email protected]>

weierophinney force-pushed the update-index-and-quick-start-guide branch from 6b1de29 to e931241 Compare October 6, 2020 14:45

weierophinney added this to the 3.1.1 milestone Oct 6, 2020

docs: incorporate feedback

05f0492

This patch incorporates feedback as provided by @froschdesign. Signed-off-by: Matthew Weier O'Phinney <[email protected]>

weierophinney merged commit 05f0492 into laminas:3.1.x Oct 6, 2020

github-actions bot mentioned this pull request Oct 6, 2020

Merge release 3.1.1 into 3.2.x #31

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Rework the Index and Quick Start guide #24

Rework the Index and Quick Start guide #24

settermjd commented Sep 16, 2020 •

edited

Loading

froschdesign left a comment

settermjd commented Sep 23, 2020

froschdesign left a comment

froschdesign Sep 23, 2020

froschdesign Sep 23, 2020

froschdesign Sep 23, 2020

froschdesign Sep 23, 2020

froschdesign Sep 23, 2020

froschdesign commented Sep 23, 2020

Rework the Index and Quick Start guide #24

Rework the Index and Quick Start guide #24

Conversation

settermjd commented Sep 16, 2020 • edited Loading

Description

froschdesign left a comment

Choose a reason for hiding this comment

settermjd commented Sep 23, 2020

froschdesign left a comment

Choose a reason for hiding this comment

froschdesign Sep 23, 2020

Choose a reason for hiding this comment

froschdesign Sep 23, 2020

Choose a reason for hiding this comment

froschdesign Sep 23, 2020

Choose a reason for hiding this comment

froschdesign Sep 23, 2020

Choose a reason for hiding this comment

froschdesign Sep 23, 2020

Choose a reason for hiding this comment

froschdesign commented Sep 23, 2020

settermjd commented Sep 16, 2020 •

edited

Loading