1. Help With Editing the Euphoria Documentation

Forked from Re: Roadmap to Euphoria 4.2

I wanted to put this (slightly modified) in its own thread so I don't keep losing it, and so people know how to help:

ghaberek said...

The documentation is generated from the code in include/std and the text files in docs/ (refman_2.txt, etc.). The only way to update the docs is to edit these files.

Here is the approximate workflow you'll need:

  1. Create a fork of the Euphoria source code
  2. Generate the HTML docs using eudoc and creole.
  3. Open the HTML docs in your browser and review.
  4. Make your corrections to the source or text files.
  5. Commit your changes to your local git repo.
  6. Repeat steps 2-5 until you're done.
  7. Push your commits to your GitHub repo.
  8. Create a pull request.

new topic     » topic index » view message » categorize

2. Re: Help With Editing the Euphoria Documentation

You have to join github, get permission to edit Euphoria, figure out how to use it, and go through lots of steps to edit the docs--way too much overhead.

The docs will be available as editable wiki pages so anyone who signs into the form can make a contribution. No extra effort required means we can get more people to casually add to the documentation.

Moving changes to github is something else; not something contributors to the docs should have to worry about.

_tom

new topic     » goto parent     » topic index » view message » categorize

3. Re: Help With Editing the Euphoria Documentation

Just want to clarify:

_tom said...

...get permission to edit Euphoria...

You do not have to get permission. Once you clone (or fork) the repository, you can edit Euphoria to your heart's content. When you're ready to push those changes back to the primary Euphoria repo, it will be reviewed first. Of course.

new topic     » goto parent     » topic index » view message » categorize

4. Re: Help With Editing the Euphoria Documentation

So, doing everything possible to prevent any collaboration on the docs.

Why?

I know that I can find hundreds of errors or misleading statements and examples in the existing docs - all by myself.

But I also know that other people will find mistakes I miss. Perhaps have better demo code or other good ideas.

That doesn't bother me, I welcome the help.

If each of us independently contributes our own version of the improved docs, who is going to go thru all that code and combine the good ideas

I suspect the answer is "nobody". It's too much work for one person. Which will be the excuse for never making any improvements.

new topic     » goto parent     » topic index » view message » categorize

5. Re: Help With Editing the Euphoria Documentation

euphoric said...

Just want to clarify:

_tom said...

...get permission to edit Euphoria...

You do not have to get permission. Once you clone (or fork) the repository, you can edit Euphoria to your heart's content. When you're ready to push those changes back to the primary Euphoria repo, it will be reviewed first. Of course.

So, let's say 5 people edit their copies of the source code (without accidentally or intentionally introducing bugs into the working code). There are several hundred changes required to the documentation.

If all 5 manage to correct every mistake they find, there will be 5 versions for each routine. Several thousand in all. They will not be identical, since no opportunity has been allowed for collaboration or discussion.

Whoever does the review will have to examine each for correctness, combine the good ideas from each, test the codes, and then reformat each to provide a consistent look to the docs.

All changes to the source will have to be done manually so that there's no chance of overwriting good working routines with buggy code.

Who is that reviewer? Does he or she have the time to do all that?

Worst of all, without a chance for discussion, somewhere between 4 and 5 of the 5 contributors are going to be unhappy that their contributions were just silently ignored.

new topic     » goto parent     » topic index » view message » categorize

6. Re: Help With Editing the Euphoria Documentation

I make a fork of the Euphoria Github. Some cookie on my computer remembered my lost password. The fork took only one click. Greg's enthusiasm for easy to use Github has been demonstrated to be true.

I will be content to "do my thing" and generate a set of docs. Changes can be make without interference to original Euphoria source-code.

How does Irv (and hopefully many others) access this fork to contribute?

_tom

new topic     » goto parent     » topic index » view message » categorize

7. Re: Help With Editing the Euphoria Documentation

irv said...
euphoric said...

Just want to clarify:

_tom said...

...get permission to edit Euphoria...

You do not have to get permission. Once you clone (or fork) the repository, you can edit Euphoria to your heart's content. When you're ready to push those changes back to the primary Euphoria repo, it will be reviewed first. Of course.

So, let's say 5 people edit their copies of the source code (without accidentally or intentionally introducing bugs into the working code). There are several hundred changes required to the documentation.

If all 5 manage to correct every mistake they find, there will be 5 versions for each routine. Several thousand in all. They will not be identical, since no opportunity has been allowed for collaboration or discussion.

Whoever does the review will have to examine each for correctness, combine the good ideas from each, test the codes, and then reformat each to provide a consistent look to the docs.

All changes to the source will have to be done manually so that there's no chance of overwriting good working routines with buggy code.

Who is that reviewer? Does he or she have the time to do all that?

Worst of all, without a chance for discussion, somewhere between 4 and 5 of the 5 contributors are going to be unhappy that their contributions were just silently ignored.

You just described why I am so slow (and I thought it was old age.)

In any writing project one person has to impose a "voice" and "style" on the writing. It becomes very obvious when random people do random contributions.

Lets say I am the editor. The wiki lets Irv (and many others) supply me with content. I see no other way than filtering the docs through me for the final edition.

If Euphoric can do it that's even better. It still has to be one person.

_tom

new topic     » goto parent     » topic index » view message » categorize

8. Re: Help With Editing the Euphoria Documentation

Having the docs available for "updating" is the way to go. We can all see, and edit if we wish. Other people can see my edits, and make better suggestions if they want. Any one can test the demos, and make notes if they don't work, or suggest better demos.

We all work on the same copy of the page(s). When I make an edit or addition, my name appears at the bottom as "last edited by". We can (theoretically, at least) roll back if necessary.

So, by the time everything has been examined and discussed, you can produce a final copy in a standard consistent format. Without having to judge, test, and combine several different versions of each doc page.

The other way will only result in what we have now. Non-working docs, because those were made from the source code comments without input from any users.

new topic     » goto parent     » topic index » view message » categorize

9. Re: Help With Editing the Euphoria Documentation

I find myself in agreement with this approach.

Let regular users edit a live copy of the docs on the wiki (or elsewhere if that makes more sense ala Google Docs or similar).

The docs in the source code do need to be updated, but the eight step workflow could easily scare away non-developers. So it makes sense to have a lot of the "doc development" on the wiki, and have _tom grab the wiki changes and update the source code manually prior to a new release. _tom isn't afraid to take on the github workflow, but a newbie potential doc editor might be.

Anyone who wants to contribute anything more than a doc change (say someone wants to update one of the stdlib include files) will need to go through the github workflow, but at that point the person is no longer a doc editor but a full fledged developer - and thus should be familiar with this kind of git workflow.

As for which version is "official"? The docs in the source code remain official for any actual release made (since in the process of moving doc hanges into github they'll get reviewed etc) but the wiki has the "bleeding edge" version of the docs.

new topic     » goto parent     » topic index » view message » categorize

10. Re: Help With Editing the Euphoria Documentation

irv said...

If each of us independently contributes our own version of the improved docs, who is going to go thru all that code and combine the good ideas

That's how it works. Everybody contributes their changes; the developers incorporate the valid changes and reject the invalid ones.

new topic     » goto parent     » topic index » view message » categorize

11. Re: Help With Editing the Euphoria Documentation

irv said...

So, let's say 5 people edit their copies of the source code (without accidentally or intentionally introducing bugs into the working code). There are several hundred changes required to the documentation.

Let's say 5 people notice a problem with map.e. They check the ticket system to see if it's already been reported.

It works like this:

1. Find a problem with the docs.

2. Check ticket system. Has it already been reported?

Yes. Goto 3.

No. Create a ticket for it.

3. Goto 1

This seems like a good, centralized solution for collaboration.

Does that sound reasonable?

new topic     » goto parent     » topic index » view message » categorize

12. Re: Help With Editing the Euphoria Documentation

jimcbrown said...

Let regular users edit a live copy of the docs on the wiki (or elsewhere if that makes more sense ala Google Docs or similar).

I don't think we have a set of 4.1 docs online, so the first step would be to upload that somewhere.

The workflow needs to accommodate future changes to the source without destroying the current online docs. How would that work?

new topic     » goto parent     » topic index » view message » categorize

13. Re: Help With Editing the Euphoria Documentation

Once the new 4.1 docs are online, how do we wikify it? And, again, how do we integrate future changes to the source in that online docs wiki?
Forked into: Wikifying the documentation

new topic     » goto parent     » topic index » view message » categorize

14. Re: Help With Editing the Euphoria Documentation

euphoric said...
irv said...

If each of us independently contributes our own version of the improved docs, who is going to go thru all that code and combine the good ideas

That's how it works. Everybody contributes their changes; the developers incorporate the valid changes and reject the invalid ones.

Except the existing evidence shows that the developers did not even reject the invalid docs that they themselves had written. Nor were the demos tested to see that they worked.

Should we expect something different "this time"?

new topic     » goto parent     » topic index » view message » categorize

15. Re: Help With Editing the Euphoria Documentation

irv said...

Except the existing evidence shows that the developers did not even reject the invalid docs that they themselves had written. Nor were the demos tested to see that they worked.

Should we expect something different "this time"?

The people actively contributing to the project right now are entirely different from those who were actively contributing 5-10 years ago. "The developers" then are not "The developers" now.

I don't think we should hold the current contributors responsible for the mistakes of their predecessors. I just know things need to be fixed and that we need to move forward on fixing them.

-Greg

new topic     » goto parent     » topic index » view message » categorize

Search



Quick Links

User menu

Not signed in.

Misc Menu