search

atoum / atoum-documentation

Documentation of atoum, a php unit test framework
http://docs.atoum.org
Other
10 stars 41 forks source link

Simplify the doc releasing process to get more contribution #33

Closed pimpin closed 9 years ago

pimpin commented 10 years ago

Hy there, As a new atoum user, I felt so happy to read that awesome doc... Thanks so much to all contributors.

And I wanted to give my little contribution by changing some line of doc and make a PR... but the process was a bit weird to me. And I gave up.

How many contributions already lost like that ?

I can't tell. But I can propose a way that seems to me more simple to handle, share, and publish the doc.

The basic idea

The idea is to offer Github users the ability to make PR on atoum doc only with their favorite browser through marvelous Github's services and manly Github pages.

Changes that imply

It involves changes that you should accept before I spent time on a PR:

Please tell me if you will approve this kind of change before I start to work on any PR.

Cheers

jubianchi commented 10 years ago

@pimpin I agree with you that in the first place, but in the end it's quite simple ;)

The main problem to me is that the tools are split in two repositories and so, the publishing process is sometimes awkward.

changing markup language from skril to markdown (that are quite similar)

I don't think that changing the markup language is a solution as it implies a lot of work. But I agree with the fact that skriv is not well known. It can be a problem for some people but we like things that are different. Also, @marmotz did a great work searching for a markdown alternative to avoid some limitations.

having a small ruby stack on any server you'd like to host the doc pages

I don't think the sort of stack is necessary and I'll explain what I think could be better.

To ease the process of testing and submitting patch to the doc, I would more likely use well know and simple tools. In the end, the doc in its current state, is just a plain static website. We have many alternatives to work with such sites, locally or remotely without requiring heavy stacks. For example, we could make the publisher evolve, perhaps merge everything in a single repository or use some static site generator like @simonjodet/gumdrop or any other one that would fit our use case. We could then stick to a full PHP stack, which will be well known from contributors.

BTW, thanks for the time you spent on this proposal.

marmotz commented 9 years ago

@pimpin Thank you for your ideas.

We just migrate our documentation to ReadTheDocs.

Please let me know if this environment suits you.

pimpin commented 9 years ago

Oh yes... the ReadTheDoc is great, and it simplify contributions by PRing the sources, that are usefully linked from each doc page.

BTW, I currently do not work on Php stack and I do not plan to contribute now. But I will as soon as possible.