Documentation Part ?

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Documentation Part ?

Mike Willbanks
Hello All,

There has been a ton of talk about documentation on the list lately.  I've been doing a bit of critical thinking on it tonight and just stating that each component is documented is not going to fully help us.  When you look at the vast amount of projects the successful ones have not just simple documentation but great documentation.

I think symfony is a project that is mostly got it "right" in terms of documentation it is divided up into: a book, a cookbook, components and a reference.  You go to things like Drupal where the documentation is made up of mostly guides.  CakePHP where it is mostly a book along with a supplied API.  Overall these projects kick our ass at documentation.

So let's talk about the way forward.  First and foremost we need to determine an approach.  Without an approach, documentation standards and a simple and approachable process; we will simply FAIL and the community will have troubles adding to the documentation.

IMO I believe we need a few things:

1. Tutorial - Which is already there!
2. Book / Guide style documentation
    a. This is the most severely lacking area.
    b. This area should talk about how the components work together
    c. Provide common use cases and show an ease of use.
3. Component documentation
    a. We have a start on this but it is not consistent
    b. The language used through out the documentation is not consistent
    c. Each component is described differently.  We need to standardize an approach.
4. Documentation design
    a. It should be easy and clear to read
    b. It should work with multiple devices
    c. When you build the documentation it should be styled properly
        - Right now it is the normal style which is horrific to look at / read


Now that I have officially thrown shit to the wind; we need to talk about how we can get here.

1. We need to build out a documentation team.
2. The documentation teams first order of business should be to determine:
    a. Documentation approach - where is our first focus?
    b. Standardize the documentation format and rules around it.  I know I just copy what was common with something else and that's how I decide to document something.  So we need a standard here.
    c. Provide a recommendation of words to use, not to use and when to use certain formatting.
3. Ask for help!  Outreach is major here; we all do not mind writing documentation just need more guidance.
4. Let's get to the point where people love our documentation and love the framework.  The two go hand in hand.

/rant

Mike
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Part ?

zionsg
This post has NOT been accepted by the mailing list yet.
Mike Willbanks wrote
2. The documentation teams first order of business should be to determine:
    b. Standardize the documentation format and rules around it.  I know I
just copy what was common with something else and that's how I decide to
document something.  So we need a standard here.
A suggestion for a standard structure for each component:
1) Component name and namespace
2) Summary
3) Basic Example
4) Workflow
5) Configuration
6) CRUD - Create, Retrieve, Update, Delete
7) Sub-components

Basic Example will show the simplest and shortest example to get the reader going. Sometimes the reader just wants to know how to get it working first and not have to dig deep thru tons of text.

Workflow explains the general workflow and probably some in-depth explanation. Example using a excerpt from this thread: Apply filters before validation
Matthew Weier O'Phinney wrote
The workflow for forms is:
- setData()
- isValid()
- getData() (or, if using object binding, just access the object you bound)
- OR getMessages() (if the form was invalid)
Configuration refers more to configuration via application.config.php, module.config.php, Module.php, global.php, local.php, etc. This section can be used to cover the config keys for Zend\ServiceManager - example from Rob Allen's notes

CRUD is just a rough guideline as developers are quite familiar with it. Creation covers the initial construction (and relevant options) for the component, Retrieval covers things like getting of data and rendering, Update covers how to modify the instance midway (eg. addMessage is used for update while setMessage is used during creation) and Delete covers how to dispose of the instance (eg. sessions).

Sub-components will basically function as a "Next" link. Like for Zend Form, the sub-components would be Fieldset, Element, etc.

Just my 2 cents' worth...
Zion Ng
Website: http://intzone.com
Singapore
Reply | Threaded
Open this post in threaded view
|

Re: Documentation Part ?

zionsg
This post has NOT been accepted by the mailing list yet.
In reply to this post by Mike Willbanks
Mike Willbanks wrote
4. Documentation design
    a. It should be easy and clear to read
    b. It should work with multiple devices
    c. When you build the documentation it should be styled properly
        - Right now it is the normal style which is horrific to look at /
Case in point would the current API documentation.
I'm not sure if it is the intended behaviour, but all the components on the left hand side are expanded.
Hard to read: ZF 2.2 API docs
Much easier to navigate and maximizes screen space: ZF 1.10 API docs
Zion Ng
Website: http://intzone.com
Singapore