Moving some parts of the documentation

[Grummfy]

Hello, I think we should move some parts in the documentation.

• "In start with atoum"
  • install part is good
  • the part about framework should be mention and refer to cookbook parts
  • we should improve this chapter with a "start from an example" by giving some stuff like docker or repository with some small tests
• The mock should go higher in the hierarchy
• The cookbooks and writing help are a bit messy but I don't see any way to reorganise it

What do you think about? @atoum/all

[agallou]

• :+1: on moving the frameworks to the cookbook parts
• for the start from an example, I like the idea of repository with small tests but don't see how docker feets here (atoum is pretty easy to install for a PHP developper).
• :+1: on moving mocks on a higher hierachy
• for the cookbook
  • for me the "Optimize PHP to run the tests as fast as possible" seems useless and could be removed
  • we could have a structure like this :
  • Examples : containing "change the default namespace" and "test of a singleton"
  • Integration with CI tools : replacing "Use with continous integration tools (CI)"
  • Integration in frameworks : replacing "Use with frameworks"
  • Integration with version control systems : containing "Hook Git"
  • Integration with other test tools : containing "Use in behat"

[Grummfy]

thanks

@marmotz @jubianchi @Hywan @vonglasow ... any comment?

[marmotz]

Hello,

Hello !

I think we should move some parts in the documentation.

I think we could reorganize documentation !

"In start with atoum" install part is good the part about framework should be mention and refer to cookbook parts

We just have to add a link to cookbook chapter ? http://docs.atoum.org/en/latest/cookbook.html#use-withn-symfony-1-4 http://docs.atoum.org/en/latest/cookbook.html#use-with-symfony-2 (Why symfony 2 is before 1.4 ?)

we should improve this chapter with a "start from an example" by giving some stuff like docker or repository with some small tests

I like this idea. We could do a simple but classical todolist application and add unit tests with a docker to launch quickly the project ? And a travis conf file !

The mock should go higher in the hierarchy

i don't understand what you're talking about

The cookbooks and writing help are a bit messy but I don't see any way to reorganise it

Maybe we should add a tutorial part on atoum.org website (written by us), move all cookbook on atoum.org/tutorials and just link tutorials (with a brief description) on documentation ? And we should add links to other tutorials (on other website) ?

Or we could be drawn by symfony cookbook documentation. First, Symfony cookbook documentation is seperate from documentation. Secondly, there are some big chapter (Assetic, Bundles, Cache, Configuration,...) and a list of question.

[Grummfy]

@Hywan & @jubianchi can you comment on this?

[Hywan]

@Grummfy I agree with the fact that the documentation is not correctly laid out. The current plan is the following:

• Start with atoum
• Integration of atoum in your IDE
• Running tests
• Command line options
• Writing help
• Asserters
• Cookbook
• External resources
• Extensions
• Contribute
• Having fun with atoum
• Quotes

First, I would move “Integration of atoum in your IDE” down. While it sounds good to be here (the user must be ready before starting writing tests), it postpones the moment where the user will actually use atoum. The name of the section is self-describing and it won't be a problem to move it down: The user will be able to find it easily.

Second, I would like to see a “First test suites” Section just after “Start with atoum”. We should introduce basic concept of testing, writing test cases and test suites. Just an overview. Then it makes sense to have the “Running tests” Section.

Third, the “Command-line options” can move down too. This is not what the user would like to read now. This is useful, necessary, but not in that place.

Fourth, the “Writing help” Section is not well named. I would see “Best practises” or “How to write a test case” (or “How to properly write a test case”). I guess this is better. At this step, the user has written a small test suites, been able to execute it, now it needs more skills to write test cases, especially to learn the “atoum' syntax”.

Fifth, the “How to write a test case” Section (ex-“Write help” Section) contains sub-sections that are not well located, such as “The loop mode” or “The debug mode”. This latter can be at the top-level under the “Debugging test cases” name.

Sixth, still on sub-sections. The “The initilization methods” is not well-located too. I would see something like a “Extending atoum” Section. This is more natural.

Seventh, the mock Sections are not well-located too. They should move in their own topSections.

Eighth, the “Execution engine” should move to its own top Section too.

So here is the plan I am proposing:

• Start with atoum
• First test suites
• Running tests
• How to write test cases (ex-Writing help)
• Asserter collection
• Mocking systems (ex-Writing help/The mocks & co.)
• Execution engines (ex-Writing help/Execution engine)
• Loop mode (ex-Writing help/The loop mode)
• Debugging test cases (ex-Writing help/The debug mode)
• Extensions
• Command line options
• Extending atoum (with ex-Writing help/The initialization methods)
• Cookbook
• Integration of atoum in your IDE
• Contribute
• External resources
• Having fun with atoum
• Quotes

Thoughts?

[marmotz]

IMHO, "loop mode" is not a debug tool, it's a writing/executing tool. So I'd move it on "Running tests" section.

[jubianchi]

:+1: with what @Hywan proposed and :+1: with @marmotz comment.

I also think the "Debugging test cases (ex-Writing help/The debug mode)" section should be closer to "How to write test cases"

[Grummfy]

Thanks for your comment. A lot of work to do, but it will be good ;)

[Hywan]

@Grummfy Extract the proposal in a list. Do one commit per item in this list. We will see the progression and will be able to help!

[Hywan]

@marmotz +1 for your suggestion.

[Grummfy]

Yep, no time for now. I'm too busy. Be back in 1 week Le 25 janv. 2016 9:43 PM, "Ivan Enderlin" notifications@github.com a écrit :

@marmotz https://github.com/marmotz +1 for your suggestion.

— Reply to this email directly or view it on GitHub https://github.com/atoum/atoum-documentation/issues/172#issuecomment-174656602 .

[Grummfy]

I think something like that could be good

• Start with atoum
• First test suites ("suites" will confuse people regarding the other unit test framework)
• Running tests
• How to write test cases
• Asserter collection
• Mocking systems
• Execution engines
• Loop mode
• Debugging test cases
• Extending atoum (with ex-Writing help/The initialization methods) => Fine tuning atoum behaviour / atoum fixtures ?
• Cookbook
• Configuration & bootstraping
  • Having fun with atoum (to rename)
• Integration of atoum in your IDE
• Command line options
• Extensions
• Contribute
• External resources
• Quotes

[jubianchi]

should we move the Quotes section to the website ?

I thin it would be better there.

[Grummfy]

yep, totaly, and the external resources?

[jubianchi]

@Grummfy totally :+1:

[Grummfy]

see

• 178

• 179

• 180

[Hywan]

@Grummfy If you prefer yes. Just start doing it. We can modify at any time later :-)!

[Grummfy]

Yes I have started it ;)

Just because modifying with crowdin is just PISA. And I still don't have found any good alternative to crowdin.

[Grummfy]

preview (from my fork) : http://atoumpreviewdoc.readthedocs.org/en/refactoring-documentation/

[Grummfy]

hello, Can I have some review about the change in terms of result (the english part only, french have not been changed)

I also take into account the issue #171

@atoum/docs @atoum/core @atoum/rms

[mikaelrandy]

I've made some improvements you can accept or not : https://github.com/atoum/atoum-documentation/pull/183

NB : WIP

[agallou]

@Grummfy :

• Annotations : i'll put this before the cookbook, extensions, contribute and "integration with the IDE" and "having fun with atoum" items.
• In fact the ordrer of the end of the menu doesn't seens right. \ For Now : * Fine tuning atoum behaviour * Cookbook * Configuration and bootstraping * Have fun with atoum * Integration of atoum in your IDE * Command line options * Extensions * Contribute * Annotations * Licenses \ What about something like that ? (as discussed previously) * Fine tuning atoum behaviour * Configuration and bootstraping * Annotations * Command line options * Cookbook * Extensions * Integration of atoum in your IDE * Have fun with atoum * Contribute * Licenses
• "Fine tuning atoum behaviour" : I think we could came up with a better title (what about just "The initialization methods" if it's the only chapter here ?)
• The "What is atoum" section could be removed now that we have the site
• +1 for issue #171 (what about the year ? does it have to be 2016 ? (it may be dynamic on documentation generation) )

Also

• about the installation : shouldn't the composer installation be the first one (about when listing the installation methods the composer link should be to the atoum's doc, not the composer website)

[Grummfy]

Thanks for the comments. I have made some changes ( @mikaelrandy some are incompatible with your changes).

So about "Fine tuning atoum behaviour" : if you have a better title, thanks to submit it. I think we can add more stuff there.

For 'what is atoum', I think it's important to add some introduction. Like the installation parts, it's important to have it.

[mikaelrandy]

@Grummfy are you sure ? https://github.com/atoum/atoum-documentation/pull/183 seems still be allowed to be merged.

[Grummfy]

Yep but I develop on my fork, I just created a PR: #184 (I will merge it tomorrow except if I got bad comment on it)

[Grummfy]

By the way, the contribute part should be moved to the website, no?

[Grummfy]

Excepting translation and the mock parts everything should be ended now. I would like to have some review.

[Grummfy]

Before going further I would like to have confirmation that it's OK. I will do the mock part after the translation and going to production (too much to write).

So can you simply say ok or not? @marmotz @mageekguy @Hywan @agallou @jubianchi @mikaelrandy thanks

example of last version on : http://atoumpreviewdoc.readthedocs.org/en/refactoring-documentation/

[agallou]

in general, looks good to me : :+1: that's easier to navigate in the docs. Thanks for your work.

Some comments :

• How to write test cases -> that's hard to classify/name this category. With this name "newTestedInstance & testedInstance" seems like it doesn't belong there (but for now I haven't a better name to propose).
• "Optimize PHP to run the tests as fast as possible"
• "For 'what is atoum', I think it's important to add some introduction" -> But isn't the intro made by the other pages of the website ?
• "Optimize PHP to run the tests as fast as possible" : what about removing this part. Do you think it's useful to have this ?

[Grummfy]

thanks for your review

1) have not found better than this, but I'm open to improvements ;) 2 & 4) It should be removed => article on the blog/website 3) I understand but don't see how to do it. And for me it's normal to have some parts in the documentation that also exist in the website.

[Grummfy]

I have made some improvements on this:

• adding number in front of title
• adding link in the intro to the website
• I have also clean a bit the cli options sections

[Grummfy]

For me this is finished, for now. So end of the week I will start to work on translation to french

[Grummfy]

let's start translation https://crowdin.com/project/atoum/fr#

[Grummfy]

see #192 for a merge ad publication as it is, I wait for your votes

preview : http://atoumpreviewdoc.readthedocs.org/en/refactoring-documentation/