1. No one cares?

The docs are available for any registered forum user to update.

There are glaring errors and omissions in the docs. At least one doc page gave a demo which was unrelated to the topic, and wouldn't work in any case. I doubt there are more than a handful of pages that are completely correct with functional demos.

Most leave out important details, such as not bothering to include the library in the demo code. When a library is included, the std/ is often forgotten. As are other includes, such as std/console.e, when display() is used in the demo. Any of these will trip up a beginner, and cause them to wonder if they should try Python instead.

So far, only 3 people seem to be interested enough to bother reviewing and correcting these. It's easy, just correct the given demo so it works, or replace it with your own which works.

So what are you waiting for?

If you need an incentive - I've edited a dozen or so pages, and already learned about some Euphoria commands I didn't know existed. I can use these in the future!

new topic     » topic index » view message » categorize

2. Re: No one cares?

Hi

How can I edit and submit a doc change, rather than just reporting it on here?

Cheers

Chris

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

3. Re: No one cares?

ChrisB said...

Hi

How can I edit and submit a doc change, rather than just reporting it on here?

Cheers

Chris

Well, up until "someone" broke it, there were links on the Wiki main page to lead to editable copies of the "Welcome to Euphoria" pages and to each doc page. Make your changes and save.

I am sure that the wiki will be feeling better soon.

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

4. Re: No one cares?

Edit OpenEuphoria Documentation

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

5. Re: No one cares?

I understand the docs aren't currently set up to allow easy modification by users, but this is simply how it is right now.

Greg is hard at work making things better; but, for now, this is the way it is.

How to contribute modifications to the Euphoria documentation.

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

6. Re: No one cares?

Leads to a blank page at the moment, but it has been working for the past 4 or 5 days just fine.

Should be back soon. In the interim, all the pages to be edited can be accessed here:

https://openeuphoria.org/wiki/pagelist.wc

Hint: only edit those which begin with the word "updating..." smile

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

7. Re: No one cares?

euphoric said...

I understand the docs aren't currently set up to allow easy modification by users, but this is simply how it is right now.

Greg is hard at work making things better; but, for now, this is the way it is.

How to contribute modifications to the Euphoria documentation.

For the past week or so, the docs have been available for editing by anyone who is registered here, and they are pretty easy to edit. I've fixed several (couple of dozen) - mostly std/console and std/convert, along with part of the "Welcome" pages.

The idea is to correct any typos and update the demos so they work by cutting and pasting the demo code.

Very few (maybe 1 out of 100) work in the current docs, and when they don't, a newcomer is entitled to assume that Euphoria is "broken".

It's been that way for years, and the only reason those problems haven't been fixed long ago is that the docs are generated from the source code comments, which leave out some very important details, and can't easily be fixed (as you point out).

The links to edit these was on the main Wiki page, which disappeared last night for some reason. I'm sure it will be restored soon. In the interim, here are the links:

https://openeuphoria.org/wiki/pagelist.wc

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

8. Re: No one cares?

irv said...

For the past week or so, the docs have been available for editing by anyone who is registered here, and they are pretty easy to edit. I've fixed several (couple of dozen) - mostly std/console and std/convert, along with part of the "Welcome" pages.

Unfortunately, any changes to the wiki will not be included in the next release, as the actual docs are generated from the source.

Please don't waste too much time editing that stuff! I'd rather you be working on EuGTK. smile

You could also create a ticket for documentation issues, with one ticket covering an entire section of the manual.

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

9. Re: No one cares?

euphoric said...
irv said...

For the past week or so, the docs have been available for editing by anyone who is registered here, and they are pretty easy to edit. I've fixed several (couple of dozen) - mostly std/console and std/convert, along with part of the "Welcome" pages.

Unfortunately, any changes to the wiki will not be included in the next release, as the actual docs are generated from the source.

Please don't waste too much time editing that stuff! I'd rather you be working on EuGTK. smile

You could also create a ticket for documentation issues, with one ticket covering an entire section of the manual.

Changes to the wiki will be part of the updated docs. It just means I will have lots of work. I will have to cut|paste the wiki changes to the source-code found at Github.

Getting "anyone and everyone" editing the wiki docs is great. The people submitting changes know much more about Euphoria and programming than I do. The effort is appreciated.

A "ticket" does not help in upgrading the docs. Editing the wiki is much more valuable.

The wiki is a crude tool for updating the docs. But, editing the source-code limits who can contribute, is even more work, and you can't see a preview of what the docs will look like without the eudoc|creole generation of html.

Github is were the docs will be preserved. The wiki is how they will be improved.

_tom

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

10. Re: No one cares?

euphoric said...
irv said...

For the past week or so, the docs have been available for editing by anyone who is registered here, and they are pretty easy to edit. I've fixed several (couple of dozen) - mostly std/console and std/convert, along with part of the "Welcome" pages.

Unfortunately, any changes to the wiki will not be included in the next release, as the actual docs are generated from the source.

Please don't waste too much time editing that stuff! I'd rather you be working on EuGTK. smile

You could also create a ticket for documentation issues, with one ticket covering an entire section of the manual.

If we are going to create the same faulty docs from the same faulty comments in the source code, let's just forget about a new release.

I have no idea where the illogical idea came from that it is possible to have up-to-date docs when they are created before people can test and find bugs in the software, and are prohibited from updating the docs to correct those mistakes.

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

11. Re: No one cares?

irv said...

I have no idea where the illogical idea came from that it is possible to have up-to-date docs when they are created before people can test and find bugs in the software, and are prohibited from updating the docs to correct those mistakes.

You're making it sound like there's some sort of Catch-22 involved when there's not.

Absolutely no one is prohibited from contributing changes to the repo. I've already detailed the workflow elsewhere.

I am asking that we correct the mistakes that currently exist. New things will be found after a release and we will correct those as they arise.

What I have no idea about, is where using the wiki for docs came up and why it's stuck. It's not what I asked for help with. It's not what we need right now.

-Greg

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

12. Re: No one cares?

To release Euphoria 4.1.1 we need:

  • updated documentation
  • a statement about the `switch` glitch
  • compiled binaries
  • bundle euGTK with release
  • include alpha libui
  • ...
  • promise that we are releasing 4.1.2 soon
  • show that 4.2 will be great

To update the docs the source-code at Github must be edited.

  • ok, so I lost my github password, and I am stuck with Mercurial thinking
  • to preview changes you must run eudoc and creole (easy for me, dubious for most)
  • updating source-code (even for documentation) is intimidating
  • the process is described here https://openeuphoria.org/forum/134389.wc
  • I remain intimidated by the process
  • I suggested there that the wiki will be the documentation path for updates

Documentation help is needed

  • so there is me
  • me also needs help
  • lets say we have 400? viewers of the forum, but we have 10? gihub members--lots of brain power but limited documentation help
  • thus the idea if the wiki was available for editing and comments we get more activity
  • surprise! massive progress

The wiki is working and broken at the same time

  • I still have to copy changes from the wiki to Github
  • At least I have a set of changes to work with
  • sorry, I broke the wiki coverpage effectively murdering the wiki (The forum has no trace that I broke the wiki so I did something clever.)

irv said... 
 
I have no idea where the illogical idea came from that it is possible to  
have up-to-date docs when they are created before people can test  
and find bugs in the software,  
and are prohibited from updating the docs to correct those mistakes. 

The wiki is supposed to be dynamic; changes can be made very simply; wiki is a good place for documentation activity. Source-code is much harder to edit; source-code is a good place to keep documentation.

The workflow from wiki to source-code is bad, but that is the way it is.

Capt. John Yossarian says docs have to be updated. The current model is static docs that will always be out of date. The online-docs are immutable!

Is anyone suggesting the `edit the docs via the wiki` should be abandoned?

_tom

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

13. Re: No one cares?

_tom said...

Is anyone suggesting the `edit the docs via the wiki` should be abandoned?

From my current understanding, yes; but only because, at this time, the docs will be completely replaced when 4.1.1 is released. All changes made to wiki docs right now will be unusable (unless tracked well enough that they can be incorporated into the 4.1.1 docs). So, maybe any changes just need to be tracked.

I'll be using the current workflow to make changes to the documentation. It's not complicated (and that says a lot coming from me); I just might not have the time to do much right now. But I'll contribute what I can.

One of the suggestions on the table is when 4.1.1 is released, and the docs are put online (it will still be generated from the source), that a provision be made to add comments to the doc pages. That way, it can at least be addended on the doc page itself. These can then be incorporated into the source much easier. Plus, with the new release schedule, they would be incorporated sooner rather than later.

After that, I'm not sure where to go. I think one way to do it is for the devs to put markers in the source indicating where documentation needs to be created (and maybe just providing bare-minimum descriptions/signatures/output/etc.). Upon some compilation, a skeletal outline is output. This outline can be used to flesh-out the online docs. Although, I really like having the docs on my PC... so...

I'm not sure that's a good idea, but if people want to separate the docs from the source, that would be a way to do it to allow input from both the programmers and the documentors.

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

14. Re: No one cares?

There seems to be a misunderstanding about documentation:

Here's how it worked when I worked in a large government shop:

Programmer comments each routine to:

  1. Indicate what input it expects
  2. What it does with that input
  3. What output is produced
  4. (if neccessary, explain code which does things in an unusual way)


These comments are to remind the programmer, and to inform future maintainers. That's all - no clutter.

Then the testers get the code, and verify (using the programmer's docs) that the routine returns the specified output when fed valid input, and that it handles invalid inputs in a correct manner. (That second part is something programmers don't do very well).

Finally, the doc writers use the program in an actual or simulated real-world situation, and write stand-alone docs in language understandable to the average user. These docs can be as detailed as necessary, illustrated if appropriate, and none of this belongs in the source code!

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

15. Re: No one cares?

Irv and I are thinking alike. I just don't know how the final details will work.

I could be educated to understand how tickets and Github can be used to create collaborative documentation. I am very slow in such matters and it will take significant effort to achieve this education.

The good news is my internet is browned out. That means for the next few days I will do gardening, maybe go fish'n, or do some other useful activity.

_tom

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

16. Re: No one cares?

irv said...

These docs...

That sounds like something that has been proposed, and I think it's a great idea!

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

17. Re: No one cares?

My thoughts:

Heredoc is/was better than nothing, but only just. The manuals it produces are /always/ pretty rubbish. Theoretically there should be a slight benefit from having the examples near to hand for updating, but since that is the number one complaint... You all heard the one about the guy who painted his hallway through the letterbox, to me that sums up exactly just how ridiculous it all is.

If you can get docs out of source onto a wiki, only a madman would attempt to drag updates back into the source code.

In fact, you should delete all that crud lying around in the source code files pretending to be a manual.

You do however need a way to download/extract from the wiki, and build the htm/chm/pdf/whatever, for local use.

Uploading the raw wiki content back into a repository, on a fairly regular basis, and taking full advantage of the diff utils to validate each file as you do so is probably a fine idea, not that there would be much other benefit to maintaining such a repository.

PS: If you dislike chm you can usually just extract the html from them with 7-Zip, and use that (in any browser).
A few additional steps were required for phix.chm, there will be a chm2htm.exw program shipped with 0.8.1 which:
Deletes all files without an extension.
Replaces all `src="/images/` with `src="images/`.
Replaces all javascript:ExternalLink()s (with normal links)
Copies images/ into html/

As for a/my Phix-docs-wiki, my plan is just get page 1 up; then anyone can copy pages from the static files, with any necessary intermediate/breadcrumb pages, and/or maybe a chm2wiki.exw assistant for any drudgework, not that I have started/tried anything yet.

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

Search



Quick Links

User menu

Not signed in.

Misc Menu